kudurru guide
This guide tells you how to use kudurru and how to run it. It has two parts.
| Part | Read it if you | Start here |
|---|---|---|
| User guide | use a network that kudurru serves | User guide |
| Administrator guide | install, set up and run kudurru | Administrator guide |
The text follows the rules of Simplified Technical English (ASD-STE100). The rules are in Writing rules.
What kudurru is
kudurru is a DNS server. A DNS server changes the name of a site into a number that a device can use. kudurru can also refuse a name. The administrator of the network decides which names it refuses.
kudurru has these functions:
- It answers queries for the zones that you own.
- It sends all other queries to upstream DNS servers.
- It blocks names that are on block lists.
- It applies different rules to different client groups.
- It has a dashboard that shows what happens on the network.
Parts of this guide
| Chapter | Content |
|---|---|
| User guide | The block page, how to ask for access, and the dashboard for viewers |
| 1. Overview | Terms, roles and the layout of the dashboard |
| 2. Install and first sign-in | Start kudurru, sign in and point the network at it |
| 3. Watch the network | Dashboard, query log and long-term statistics |
| 4. Block lists and domains | Lists, the Allowlist and the Denylist |
| 5. Groups, clients and policies | Decide which rules apply to which device |
| 6. Access requests | The block page and the answers to users |
| 7. Zones and upstreams | Your own DNS names and the external servers |
| 8. System pages | Nodes, settings, tools and diagnosis |
| 9. People, roles and tokens | Who can sign in and what they can do |
| 10. Command line | The kudurru command |
| 11. Maintenance | Back up, restore, upgrade and recover |
| 12. Troubleshooting | Problems and their solutions |
How to read this guide
- Each chapter starts with Before you start. It lists the role and the items that you need.
- Numbered steps are procedures. Do the steps in the order that they have.
- A line that starts with
CAUTION:tells you about a risk. Read it before you do the step. - Bold text is text that you see on the screen.
Codetext is text that you type, a file name or a value. - The screenshots show demo data. The names and numbers on your system are different.
Version
This guide describes kudurru 0.1. This version is a release candidate. The list of open items is in the release checklist. Some functions are for later versions. The guide says so where it matters.
More information
| Subject | Document |
|---|---|
| All deployment shapes (Docker, Kubernetes, packages) | Deploying kudurru |
| Backup, key rotation and upgrade runbooks | Runbooks |
| The design of kudurru | Architecture |
| Every setting | Settings reference |
| Every command | Command reference |
| Move from Pi-hole | Coming from Pi-hole |