docs: rewrite for people running nxdns; query-history refusals name their remedy and a refused start gives no wrong hints
This commit is contained in:
@@ -1,90 +1,55 @@
|
||||
# Back up and restore
|
||||
|
||||
The configuration is the only state worth keeping. `nxdns export` writes it out as a ZON file and `nxdns import` writes one back. The query log is deliberately not part of a backup: it is expendable history, and if it is missing it gets recreated empty.
|
||||
The configuration is the only state worth backing up. The query history is not part of a backup, and the blocklists download again on their own.
|
||||
|
||||
**Which authority the service runs under decides what the backup *is*.** Check the start log:
|
||||
What the backup is depends on the mode nxdns runs in. The start log says which:
|
||||
|
||||
- `authority: database` — `config.db` holds the configuration. Back it up with `nxdns export`, and restore with `nxdns import` or by replacing the database file.
|
||||
- `authority: file (<path>)` — that file holds the configuration, and it is already a text file you can keep in git. **The file is the backup.** Restoring means putting the file back and restarting; the database rebuilds itself from it. `config.db` is a cache of the file in this mode, not the thing to preserve.
|
||||
- `authority: database`: the configuration lives in `config.db`. Back it up with `nxdns export` and restore it with `nxdns import`. The rest of this page is about this mode.
|
||||
- `authority: file (<path>)`: the configuration is that file, and the file is the backup. To restore, put the file back and start nxdns; it rebuilds its database from the file.
|
||||
|
||||
The rest of this page covers database mode unless it says otherwise.
|
||||
|
||||
The commands below use the scratch lab from [enable DoH and DoT](enable-doh-and-dot.md), data directory `/tmp/nxdns-lab/data`. On a real install drop `--data-dir` and the default `/var/lib/nxdns` applies.
|
||||
The commands below use the default data directory, `/var/lib/nxdns`. Add `--data-dir DIR` if yours is elsewhere.
|
||||
|
||||
## Back up
|
||||
|
||||
One command, against a stopped or a running server:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/backup.zon
|
||||
nxdns export --out /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup.zon
|
||||
wrote /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
The write is a temp file plus a rename, so an interrupted export leaves no half-written backup, and the result is mode 0600:
|
||||
This works while nxdns is running. The file is written in one step, so an interrupted export leaves no half-written backup, and it is created at mode 0600 because it carries the admin password's hash:
|
||||
|
||||
```sh
|
||||
stat -c '%a %n' /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
```
|
||||
600 /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
That mode is not decoration. The file carries `web.password_hash`:
|
||||
|
||||
```sh
|
||||
grep password /tmp/nxdns-lab/backup.zon
|
||||
```
|
||||
|
||||
```
|
||||
```zon
|
||||
.password = null,
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$hOjjnTrTZ6kU8XrwQuJ7ZFC3B5LumaB4hRe7kBbzJ6Q$YsC2rCTDKv96eEwPhs+D6vbDliLogEZph8EkagKSuy8",
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…",
|
||||
```
|
||||
|
||||
Treat backups as secrets. `.password` is always exported as `null` — the plaintext is never stored anywhere — so the file re-imports without anyone knowing the password. `null` and `""` are different statements here: `null` means the file says nothing about the password, while an empty `password_hash` would disable authentication. See [Password and hash](../reference/configuration.md#password-and-hash).
|
||||
The plaintext password is never stored, so `.password` is always `null`, and the file restores the same password without anyone knowing it. Keep backups as private as the database.
|
||||
|
||||
Without `--out` the export goes to stdout, where the file mode is your redirect's problem:
|
||||
Without `--out`, the export goes to standard output.
|
||||
|
||||
An export holds configuration only: settings, groups, upstreams, devices you named, blocklist sources, rules and local records. It leaves out what the server records while it runs, such as when a device was last seen or how many domains a list held, so two exports of the same configuration are identical.
|
||||
|
||||
## Restore onto a new machine
|
||||
|
||||
On an empty data directory, `import` loads the backup:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data | head -10
|
||||
```
|
||||
|
||||
```
|
||||
// nxdns configuration
|
||||
// generated by `nxdns export` from the running configuration
|
||||
.{
|
||||
.upstream = .{
|
||||
.attempt_timeout_ms = 2500,
|
||||
.read_timeout_ms = 3000,
|
||||
.total_timeout_ms = 5000,
|
||||
},
|
||||
.dns = .{
|
||||
.bind_ipv4 = "127.0.0.1",
|
||||
```
|
||||
|
||||
Runtime facts are left out on purpose: client first-seen and last-seen times, rule creation times, per-source domain counts and checksums. They are things a running server produces, not configuration, and including them would make two exports taken minutes apart differ.
|
||||
|
||||
## Restore onto a fresh data directory
|
||||
|
||||
This is the normal restore: new machine, new disk, empty data directory. Nothing to overwrite, so nothing to authorise.
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/backup.zon --data-dir /tmp/nxdns-lab/data-restored
|
||||
nxdns import /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
```
|
||||
info(migrations): config.db migrated from schema version 0 to 1
|
||||
imported /tmp/nxdns-lab/backup.zon
|
||||
imported /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
The migration line is expected: `import` creates and migrates the database before writing to it.
|
||||
Under systemd, run it as root and then `chown -R nxdns:nxdns /var/lib/nxdns` before you start the service. Under Docker, see [Database mode instead](install-with-docker.md#database-mode-instead).
|
||||
|
||||
## Restore over an existing database
|
||||
## Restore over an existing configuration
|
||||
|
||||
**Stop the server first.** `import` rewrites configuration underneath a process that read it at startup, and a running server picks up only part of it — filtering follows the new rows at the next reload, while upstreams, listeners and settings stay at their boot values until a restart.
|
||||
Stop nxdns first. A running server read its configuration when it started, and would only pick up part of the change.
|
||||
|
||||
```sh
|
||||
systemctl stop nxdns
|
||||
@@ -92,97 +57,36 @@ nxdns import /var/backups/nxdns-config.zon
|
||||
systemctl start nxdns
|
||||
```
|
||||
|
||||
`import` converges the database onto the file. Rows the file still names are matched and updated in place; rows it no longer names are deleted. That last part is what a restore of an old backup does to everything added since, so it takes a flag:
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/old-backup.zon --data-dir /tmp/nxdns-lab/data
|
||||
```
|
||||
`import` makes the database match the file. Entries the file names are added or updated. Entries it does not name would be deleted, which is what restoring an old backup does to everything added since, so `import` refuses until you confirm, and changes nothing:
|
||||
|
||||
```
|
||||
FAIL import: this file would delete rows the database holds (upstreams 1); re-run with --allow-delete to apply it
|
||||
import failed: DestructiveImport
|
||||
```
|
||||
|
||||
That exits 2 and rolls the transaction back, so nothing is half-applied. The message names every table that would lose rows, which is usually enough to tell an intended restore from the wrong file. Say `--allow-delete` when deleting is what you mean:
|
||||
The message names what would go. If that is what you want, run it again with `--allow-delete`:
|
||||
|
||||
```sh
|
||||
nxdns import /tmp/nxdns-lab/old-backup.zon --allow-delete --data-dir /tmp/nxdns-lab/data
|
||||
nxdns import /var/backups/nxdns-config.zon --allow-delete
|
||||
```
|
||||
|
||||
```
|
||||
imported /tmp/nxdns-lab/old-backup.zon
|
||||
```
|
||||
Renaming a group or changing an upstream's URL counts as a deletion too: the old entry goes and a new one arrives.
|
||||
|
||||
A restore that only puts back what is already there needs no flag at all, and neither does one that only adds rows. The flag is about deletion specifically — including deletion in disguise: renaming a group, or correcting a typo in an upstream URL, changes the row's identity, so the engine sees one row gone and one arrived.
|
||||
A restore keeps what does not belong in a backup. A blocklist whose URL is still in the file keeps its download, so nothing is fetched again. Devices nxdns discovered on the network keep their history, and a device the backup names keeps the first-seen and last-seen times the database already had. A device you named by hand that the backup does not name is deleted with the rest.
|
||||
|
||||
What survives a restore is worth knowing before you take an old backup out of the drawer. Blocklist download state is kept for every source whose URL the file still names — checksum, counters, compiled files, and the row id they are keyed by — so restoring does not cost a re-download. Devices the server discovered from traffic are kept whole, and one the backup names keeps the first-seen and last-seen the database already held, so a restore never restamps your network as newly arrived. What does go is a client the backup does not name and that was named by hand: that row is declarative, and it is deleted with the rest.
|
||||
## Check a backup
|
||||
|
||||
> The three `systemctl` lines are the only commands on this page that were not
|
||||
> run: this machine has no installed nxdns unit (`systemctl status nxdns`
|
||||
> answers `Unit nxdns.service could not be found.`) and `systemctl stop`/`start`
|
||||
> need root. The `nxdns import` between them is the same command the lab blocks
|
||||
> above run, which were executed here as written.
|
||||
|
||||
## Restoring the database file itself
|
||||
|
||||
Copying `config.db` back into place works too, and it is the fastest restore on a machine that still has one. Two rules, and the second one is where restores go wrong:
|
||||
|
||||
1. **Take the copy from a stopped instance**, or use `nxdns export` instead. A copy taken while nxdns is running catches the main file without the changes sitting in its write-ahead log.
|
||||
2. **Delete any stale `config.db-wal` and `config.db-shm` beside the file you restore.** SQLite silently discards a write-ahead log that does not match the database it sits next to. It does not warn, and it does not fail — it just answers from the main file, so a restore quietly loses its own tail.
|
||||
Exporting the same configuration twice gives the same bytes, so a backup that loads and exports back unchanged is complete. To check one without touching the real data directory, load it into a scratch directory and compare:
|
||||
|
||||
```sh
|
||||
systemctl stop nxdns
|
||||
rm -f /var/lib/nxdns/config.db-wal /var/lib/nxdns/config.db-shm
|
||||
cp /var/backups/config.db /var/lib/nxdns/config.db
|
||||
chown nxdns:nxdns /var/lib/nxdns/config.db
|
||||
chmod 0600 /var/lib/nxdns/config.db
|
||||
systemctl start nxdns
|
||||
nxdns import /var/backups/nxdns-config.zon --data-dir /tmp/nxdns-check
|
||||
nxdns export --data-dir /tmp/nxdns-check --out /tmp/nxdns-check.zon
|
||||
diff /var/backups/nxdns-config.zon /tmp/nxdns-check.zon && echo "backup is complete"
|
||||
```
|
||||
|
||||
> Not verified on this host: these need root, an installed unit and
|
||||
> `/var/lib/nxdns`, none of which exist here.
|
||||
## What a backup leaves out
|
||||
|
||||
None of this applies in file mode. There `config.db` is derived state — restore the configuration file and start the service, and the first reconcile rebuilds the database from it.
|
||||
- `querylog.db`, the query history. nxdns creates an empty one when it is missing. To keep the history as well, copy `querylog.db` while nxdns is stopped.
|
||||
- `blocklists/`, the downloaded lists. They come back from the sources the configuration names.
|
||||
|
||||
## Verify a backup
|
||||
|
||||
The round trip is byte-stable: exporting, importing and exporting again gives an identical file. That is the cheapest check that a backup is complete and that it will load.
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/backup2.zon
|
||||
diff /tmp/nxdns-lab/backup.zon /tmp/nxdns-lab/backup2.zon \
|
||||
&& echo "round trip is byte-identical"
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup2.zon
|
||||
round trip is byte-identical
|
||||
```
|
||||
|
||||
The same check works across data directories — export from the restored copy and diff against the backup you restored from:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data-restored --out /tmp/nxdns-lab/backup3.zon
|
||||
diff /tmp/nxdns-lab/backup.zon /tmp/nxdns-lab/backup3.zon \
|
||||
&& echo "restored database exports identically"
|
||||
```
|
||||
|
||||
```
|
||||
wrote /tmp/nxdns-lab/backup3.zon
|
||||
restored database exports identically
|
||||
```
|
||||
|
||||
## What is not in the backup
|
||||
|
||||
Everything under the data directory other than `config.db`:
|
||||
|
||||
- `querylog.db` — expendable history, recreated empty when absent.
|
||||
- `blocklists/` — compiled snapshots. They are rebuilt from the sources named in the configuration, so restoring the configuration is enough; the first refresh after a restore downloads them again.
|
||||
|
||||
The data directory layout is in [files and directories](../reference/files-and-directories.md).
|
||||
|
||||
## A backup before every upgrade
|
||||
|
||||
There is no downgrade path. Schema migrations run forward automatically at startup and before `export` and `import`; nothing walks them back, and `nxdns check` does not run them at all. Take an export before installing a new binary — see [upgrade](upgrade.md).
|
||||
|
||||
Every `nxdns` command on this page was executed on this host as written. The `systemctl`, `cp`, `chown` and `chmod` lines were not: they need root and an installed unit, and both blocks holding them say so.
|
||||
[Files and directories](../reference/files-and-directories.md) lists everything in the data directory.
|
||||
|
||||
@@ -1,247 +1,23 @@
|
||||
# Enable DoH and DoT
|
||||
|
||||
nxdns can answer encrypted queries on two extra listeners: DNS over HTTPS (`doh_server`) and DNS over TLS (`dot_server`). Both are off by default and both need a certificate and a private key in PEM form.
|
||||
Besides plain DNS on port 53, nxdns can answer encrypted queries from your devices: DNS over HTTPS (DoH) on port 443 and DNS over TLS (DoT) on port 853. Both are off by default, and both need a certificate and its private key, as PEM files.
|
||||
|
||||
This page uses a scratch lab under `/tmp/nxdns-lab` so the commands run without root and without touching a real install. On a real install the files live under `/etc/nxdns` and the data directory is `/var/lib/nxdns`; the ports are 443 and 853 rather than the unprivileged ones below.
|
||||
## 1. Get a certificate
|
||||
|
||||
Every field mentioned here is documented in [configuration reference](../reference/configuration.md).
|
||||
Devices check the certificate against the name you give them, so use a certificate for a name you control, from an ACME client such as certbot, lego or Caddy. Android's Private DNS setting, for example, takes a hostname and needs a certificate a phone trusts.
|
||||
|
||||
## 1. Get a certificate and key
|
||||
|
||||
For a LAN service the practical options are a certificate from your ACME client (certbot, lego, caddy) for a name you control, or a self-signed pair. The lab below uses a self-signed pair, because it needs no domain:
|
||||
|
||||
```sh
|
||||
mkdir -p /tmp/nxdns-lab/etc
|
||||
cd /tmp/nxdns-lab
|
||||
openssl req -x509 -newkey rsa:2048 -nodes \
|
||||
-keyout etc/key.pem -out etc/cert.pem -days 365 \
|
||||
-subj "/CN=nxdns.lan" \
|
||||
-addext "subjectAltName=DNS:nxdns.lan,DNS:localhost,IP:127.0.0.1"
|
||||
chmod 0600 etc/key.pem
|
||||
```
|
||||
|
||||
A self-signed certificate means every client has to be told to trust it, or told to skip verification. That is why the client commands further down pass `--insecure` and `+tls` without a CA. A real deployment uses a real certificate and drops those flags.
|
||||
|
||||
## 2. Turn the listeners on
|
||||
|
||||
`cert_path` and `key_path` must be absolute, or relative to the process working directory. Point both endpoints at the same pair unless you have a reason not to:
|
||||
|
||||
```zon
|
||||
.{
|
||||
.groups = .{.{ .name = "default" }},
|
||||
.upstreams = .{.{ .url = "https://cloudflare-dns.com/dns-query" }},
|
||||
.dns = .{ .bind_ipv4 = "127.0.0.1", .bind_ipv6 = "::1", .port = 15400 },
|
||||
.web = .{ .bind = "127.0.0.1", .port = 8451, .password = "lab-password" },
|
||||
.doh_server = .{
|
||||
.enabled = true,
|
||||
.bind = "127.0.0.1",
|
||||
.port = 8443,
|
||||
.cert_path = "/tmp/nxdns-lab/etc/cert.pem",
|
||||
.key_path = "/tmp/nxdns-lab/etc/key.pem",
|
||||
},
|
||||
.dot_server = .{
|
||||
.enabled = true,
|
||||
.bind = "127.0.0.1",
|
||||
.port = 8853,
|
||||
.cert_path = "/tmp/nxdns-lab/etc/cert.pem",
|
||||
.key_path = "/tmp/nxdns-lab/etc/key.pem",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Write that to `/tmp/nxdns-lab/etc/config.zon`. The lab runs `nxdns run --config`, which makes that file the configuration: every start reconciles the database onto it, so editing the file and restarting is how these settings change here. A real install may instead run bare `nxdns run` and keep the configuration in the database — see [the configuration model](../explanation/configuration-model.md).
|
||||
|
||||
## 3. Check the files before starting
|
||||
|
||||
```sh
|
||||
nxdns check --data-dir /tmp/nxdns-lab/data --config /tmp/nxdns-lab/etc/config.zon
|
||||
```
|
||||
|
||||
```
|
||||
checking configuration file /tmp/nxdns-lab/etc/config.zon
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
OK: no problems found
|
||||
```
|
||||
|
||||
`check` loads both endpoints' certificate and key the same way the listeners do, so what passes here will start. An unreadable file is a failure and exits 2:
|
||||
|
||||
```
|
||||
FAIL doh_server.cert_path: '/tmp/nxdns-lab/etc/cert.pem': certificate file is not readable
|
||||
FAIL dot_server.cert_path: '/tmp/nxdns-lab/etc/cert.pem': certificate file is not readable
|
||||
```
|
||||
|
||||
So is a key that does not belong to the certificate, which is the mistake worth catching before a restart — the two files are individually valid and only their pairing is wrong. mbedTLS writes its own line to stderr as it rejects the pair:
|
||||
|
||||
```
|
||||
warning(tls_server): mbedtls_pk_check_pair failed: RSA - Key failed to pass the validity check of the library (-16896)
|
||||
warning(tls_server): mbedtls_pk_check_pair failed: RSA - Key failed to pass the validity check of the library (-16896)
|
||||
checking configuration file /tmp/nxdns-lab/etc/mismatch.zon
|
||||
FAIL doh_server.key_path: '/tmp/nxdns-lab/etc/other.pem': private key does not belong to the certificate
|
||||
FAIL dot_server.key_path: '/tmp/nxdns-lab/etc/other.pem': private key does not belong to the certificate
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
```
|
||||
|
||||
A key readable by anyone but its owner is a warning instead. It does not change the exit code, because the service still starts, and the summary line counts it rather than claiming nothing was found:
|
||||
|
||||
```
|
||||
WARN doh_server.key_path: '/tmp/nxdns-lab/etc/key.pem' is mode 644; a TLS key must be readable by its owner only
|
||||
WARN dot_server.key_path: '/tmp/nxdns-lab/etc/key.pem' is mode 644; a TLS key must be readable by its owner only
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
OK: no failures found, 2 warnings
|
||||
```
|
||||
|
||||
## 4. Start and confirm the listeners
|
||||
|
||||
```sh
|
||||
nxdns run --data-dir /tmp/nxdns-lab/data --config /tmp/nxdns-lab/etc/config.zon
|
||||
```
|
||||
|
||||
Two lines in the log say the listeners bound:
|
||||
|
||||
```
|
||||
info(nxdns): doh listener on 127.0.0.1:8443
|
||||
info(nxdns): dot listener on 127.0.0.1:8853
|
||||
```
|
||||
|
||||
If a certificate cannot be loaded while its endpoint is enabled, nxdns refuses to start and exits 2 rather than serving DNS without the listener you asked for:
|
||||
|
||||
```
|
||||
doh_server: '/tmp/nxdns-lab/etc/cert.pem' + '/tmp/nxdns-lab/etc/key.pem': private key file is not readable
|
||||
nxdns run failed: BadCertificate
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
## 5. Query DoT
|
||||
|
||||
Recent `dig` speaks DNS over TLS with `+tls` (this page was checked with BIND 9.20.26):
|
||||
|
||||
```sh
|
||||
dig @127.0.0.1 -p 8853 +tls example.com A +short
|
||||
```
|
||||
|
||||
```
|
||||
172.66.147.243
|
||||
104.20.23.154
|
||||
```
|
||||
|
||||
## 6. Query DoH
|
||||
|
||||
The only path the DoH listener serves is `/dns-query`; anything else is a 404. It accepts both the POST form (the query as an `application/dns-message` body) and the GET form (`?dns=` with base64url of the same bytes).
|
||||
|
||||
The body is a raw DNS query in wire format. Build one for `example.com A` — header with the recursion-desired bit, one question, then the QNAME as length-prefixed labels:
|
||||
|
||||
```sh
|
||||
printf '%s' '000001000001000000000000076578616d706c6503636f6d0000010001' \
|
||||
| xxd -r -p > /tmp/nxdns-lab/query.bin
|
||||
```
|
||||
|
||||
POST it:
|
||||
|
||||
```sh
|
||||
curl -sS --insecure --http1.1 \
|
||||
-H 'content-type: application/dns-message' \
|
||||
--data-binary @/tmp/nxdns-lab/query.bin \
|
||||
--output /tmp/nxdns-lab/answer.bin \
|
||||
-w 'http %{http_code}, %{size_download} bytes\n' \
|
||||
https://127.0.0.1:8443/dns-query
|
||||
xxd /tmp/nxdns-lab/answer.bin
|
||||
```
|
||||
|
||||
```
|
||||
http 200, 72 bytes
|
||||
00000000: 0000 8180 0001 0002 0000 0001 0765 7861 .............exa
|
||||
00000010: 6d70 6c65 0363 6f6d 0000 0100 01c0 0c00 mple.com........
|
||||
00000020: 0100 0100 0000 0400 04ac 4293 f3c0 0c00 ..........B.....
|
||||
00000030: 0100 0100 0000 0400 0468 1417 9a00 0029 .........h.....)
|
||||
00000040: 04d0 0000 0000 0000 ........
|
||||
```
|
||||
|
||||
The second flag byte `80` and the third answer-count field `0002` say: response, no error, two answer records.
|
||||
|
||||
The GET form takes the same bytes, base64url-encoded with the padding removed:
|
||||
|
||||
```sh
|
||||
Q=$(base64 -w0 /tmp/nxdns-lab/query.bin | tr '+/' '-_' | tr -d '=')
|
||||
curl -sS --insecure --http1.1 -o /tmp/nxdns-lab/get.bin \
|
||||
-w 'GET http %{http_code}, %{size_download} bytes\n' \
|
||||
"https://127.0.0.1:8443/dns-query?dns=$Q"
|
||||
```
|
||||
|
||||
```
|
||||
GET http 200, 61 bytes
|
||||
```
|
||||
|
||||
`--http1.1` matters: without it curl offers HTTP/2 over ALPN, and the DoH listener negotiates only what it advertises. `--insecure` is only needed for the self-signed lab certificate.
|
||||
|
||||
## 7. Renewals
|
||||
|
||||
A watcher polls both files every 30 seconds and compares their modification time and size against the pair currently loaded. When either differs it reloads and swaps the new pair in; connections already open finish on the old certificate. Nothing has to restart.
|
||||
|
||||
Replace the pair and wait one poll interval:
|
||||
To try it out first, a self-signed certificate is enough:
|
||||
|
||||
```sh
|
||||
openssl req -x509 -newkey rsa:2048 -nodes \
|
||||
-keyout /tmp/nxdns-lab/etc/key.pem -out /tmp/nxdns-lab/etc/cert.pem -days 365 \
|
||||
-keyout /etc/nxdns/key.pem -out /etc/nxdns/cert.pem -days 365 \
|
||||
-subj "/CN=nxdns.lan" \
|
||||
-addext "subjectAltName=DNS:nxdns.lan,DNS:localhost,IP:127.0.0.1"
|
||||
chmod 0600 /tmp/nxdns-lab/etc/key.pem
|
||||
-addext "subjectAltName=DNS:nxdns.lan,IP:192.168.1.10"
|
||||
```
|
||||
|
||||
Within 30 seconds the log says so, once per endpoint that watches the file:
|
||||
Replace `nxdns.lan` and `192.168.1.10` with the name and address your devices will use.
|
||||
|
||||
```
|
||||
info(cert_store): certificate reloaded from /tmp/nxdns-lab/etc/cert.pem
|
||||
info(cert_store): certificate reloaded from /tmp/nxdns-lab/etc/cert.pem
|
||||
```
|
||||
|
||||
## 8. Reload immediately
|
||||
|
||||
To skip the wait — from an ACME deploy hook, for example — call `POST /api/certs/reload`. It needs a session; see [set up admin authentication](set-up-admin-authentication.md) for the login call that fills `cookies.txt`.
|
||||
|
||||
```sh
|
||||
curl -sS -b /tmp/nxdns-lab/cookies.txt -X POST http://127.0.0.1:8451/api/certs/reload
|
||||
```
|
||||
|
||||
```json
|
||||
{"doh":{"enabled":true,"reloaded":true,"error":null},"dot":{"enabled":true,"reloaded":true,"error":null}}
|
||||
```
|
||||
|
||||
The route always answers 200: the per-endpoint outcome is the payload, not the status code. A disabled endpoint reports `"enabled":false`. A reload that fails names the reason and leaves the old certificate serving:
|
||||
|
||||
```sh
|
||||
chmod 000 /tmp/nxdns-lab/etc/key.pem
|
||||
curl -sS -b /tmp/nxdns-lab/cookies.txt -X POST http://127.0.0.1:8451/api/certs/reload
|
||||
```
|
||||
|
||||
```json
|
||||
{"doh":{"enabled":true,"reloaded":false,"error":"private key file is not readable"},"dot":{"enabled":true,"reloaded":false,"error":"private key file is not readable"}}
|
||||
```
|
||||
|
||||
The listeners keep working through that failure:
|
||||
|
||||
```sh
|
||||
dig @127.0.0.1 -p 8853 +tls example.com A +short
|
||||
```
|
||||
|
||||
```
|
||||
104.20.23.154
|
||||
172.66.147.243
|
||||
```
|
||||
|
||||
Undo it with `chmod 0600 /tmp/nxdns-lab/etc/key.pem` and reload again. The counters are on `/metrics`:
|
||||
|
||||
```
|
||||
nxdns_cert_reloads_total{endpoint="doh"} 3
|
||||
nxdns_cert_reloads_total{endpoint="dot"} 3
|
||||
nxdns_cert_reload_failures_total{endpoint="doh"} 2
|
||||
nxdns_cert_reload_failures_total{endpoint="dot"} 2
|
||||
```
|
||||
|
||||
## File ownership on a real install
|
||||
|
||||
The key must be readable by the user nxdns runs as, and by nobody else.
|
||||
|
||||
Under systemd the service runs as the `nxdns` user:
|
||||
The key must be readable by the user nxdns runs as, and by nobody else. Under systemd that is the `nxdns` user:
|
||||
|
||||
```sh
|
||||
chown nxdns:nxdns /etc/nxdns/cert.pem /etc/nxdns/key.pem
|
||||
@@ -249,17 +25,81 @@ chmod 0644 /etc/nxdns/cert.pem
|
||||
chmod 0600 /etc/nxdns/key.pem
|
||||
```
|
||||
|
||||
Under Docker the container runs as uid 65532, fixed in the image, and `/etc/nxdns` is a read-only bind mount — the container cannot fix permissions itself, so the host-side files must already be readable by that uid. It has no name on the host, so chown it numerically:
|
||||
Under Docker, put both files in `etc-nxdns/` next to `compose.yaml` and give them to uid 65532 the same way, since the container cannot change the read-only mount itself.
|
||||
|
||||
```sh
|
||||
cd deploy/docker
|
||||
chown 65532:65532 etc-nxdns/cert.pem etc-nxdns/key.pem
|
||||
chmod 0644 etc-nxdns/cert.pem
|
||||
chmod 0600 etc-nxdns/key.pem
|
||||
## 2. Turn the listeners on
|
||||
|
||||
In file mode, add both sections to the configuration file:
|
||||
|
||||
```zon
|
||||
.doh_server = .{
|
||||
.enabled = true,
|
||||
.cert_path = "/etc/nxdns/cert.pem",
|
||||
.key_path = "/etc/nxdns/key.pem",
|
||||
},
|
||||
.dot_server = .{
|
||||
.enabled = true,
|
||||
.cert_path = "/etc/nxdns/cert.pem",
|
||||
.key_path = "/etc/nxdns/key.pem",
|
||||
},
|
||||
```
|
||||
|
||||
**Not verified on this host:** the two `chown` blocks above. Both need root, and the systemd one needs an `nxdns` user this development machine does not have. Everything else on this page was executed as written.
|
||||
In database mode, open **System** in the web interface, tick **enabled** under **DoH Server** and **DoT Server**, check the certificate and key paths, and save.
|
||||
|
||||
## Ports 443 and 853
|
||||
Both listeners bind every address on their standard ports by default; `bind` and `port` change that. The packaged systemd unit already allows binding ports below 1024. Under Docker, uncomment the `443` and `853` lines under `ports:` in `compose.yaml`.
|
||||
|
||||
The defaults are the standard ports, which are privileged. Under the packaged systemd unit that is already handled: it grants `CAP_NET_BIND_SERVICE` for port 53 and the same capability covers 443 and 853. See [install with systemd](install-with-systemd.md).
|
||||
## 3. Check and restart
|
||||
|
||||
In file mode, `check` loads the certificate and key the same way the listeners will:
|
||||
|
||||
```sh
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
It fails when a file is unreadable or when the key does not belong to the certificate, and warns when the key is readable by others:
|
||||
|
||||
```
|
||||
FAIL doh_server.key_path: '/etc/nxdns/other.pem': private key does not belong to the certificate
|
||||
WARN dot_server.key_path: '/etc/nxdns/key.pem' is mode 644; a TLS key must be readable by its owner only
|
||||
```
|
||||
|
||||
Then restart nxdns (`systemctl restart nxdns`, or `docker compose restart`). The log names both listeners:
|
||||
|
||||
```
|
||||
info(nxdns): doh listener on 0.0.0.0:443
|
||||
info(nxdns): dot listener on 0.0.0.0:853
|
||||
```
|
||||
|
||||
If a certificate cannot be loaded, nxdns refuses to start and exits 2 rather than run without the listener you asked for:
|
||||
|
||||
```
|
||||
doh_server: '/etc/nxdns/cert.pem' + '/etc/nxdns/key.pem': private key file is not readable
|
||||
nxdns run failed: BadCertificate
|
||||
```
|
||||
|
||||
## 4. Test them
|
||||
|
||||
DoT, with a `dig` from BIND 9.18 or newer:
|
||||
|
||||
```sh
|
||||
dig @192.168.1.10 +tls example.com A +short
|
||||
```
|
||||
|
||||
DoH, using curl's own DoH resolver to look up `example.com`:
|
||||
|
||||
```sh
|
||||
curl -sS --doh-url https://nxdns.lan/dns-query -o /dev/null \
|
||||
-w 'resolved to %{remote_ip}\n' https://example.com
|
||||
```
|
||||
|
||||
Add `--doh-insecure` to the curl command while you test with a self-signed certificate. DoH is served at `/dns-query` only, over HTTP/1.1, as both GET and POST.
|
||||
|
||||
## Renewing the certificate
|
||||
|
||||
nxdns checks both files every 30 seconds and switches to a renewed pair on its own; connections already open finish on the old one. There is nothing to restart. Each reload is logged:
|
||||
|
||||
```
|
||||
info(cert_store): certificate reloaded from /etc/nxdns/cert.pem
|
||||
```
|
||||
|
||||
To load it at once instead, press **Reload certificates** on the **System** page. If a reload fails, nxdns keeps serving the certificate it has and says why.
|
||||
|
||||
@@ -1,73 +1,26 @@
|
||||
# Install nxdns with Docker
|
||||
# Install with Docker
|
||||
|
||||
Runs the published nxdns image with Docker Compose. At the end a container answers DNS on port 53 and keeps its data in a named volume.
|
||||
Run the published nxdns image with Docker Compose. At the end a container answers DNS on port 53 and keeps its data in a named volume. The image is built for `linux/amd64` and `linux/arm64`, so the same steps work on a PC and on a Raspberry Pi.
|
||||
|
||||
The image is multi-architecture — `linux/amd64` and `linux/arm64` — so the same tag works on a PC and on a Raspberry Pi 5. Building the image yourself is still supported and is the last section of this page.
|
||||
|
||||
For what each configuration field means, see [the configuration reference](../reference/configuration.md).
|
||||
|
||||
> Verification: on 2026-10-02, steps 1 to 3 were run against the published `v0.0.21` release with an image pulled anonymously from the registry, on the host ports printed below; the notes in those steps carry the detail. The failure modes in step 2 were run on the machine that wrote an earlier revision of this page, against an image built from this checkout. The `chown` to uid 65532 needs root and was not run.
|
||||
>
|
||||
> **Earlier, for the file-mode revision.** The compose file now ships
|
||||
> `command: ["run", "--config=/etc/nxdns/config.zon"]`, and no container was
|
||||
> started against that command on this host: staging a release image needs
|
||||
> `zig build dist`, which refuses to run while `admin/dist` is stale, and the web
|
||||
> bundle was being rebuilt by other work in the same tree at the time. What was
|
||||
> checked instead is `docker compose -f deploy/docker/compose.yaml config`,
|
||||
> which resolves the file without contacting a registry and prints the `command`
|
||||
> and the `:ro` bind mount as written, and the same
|
||||
> `run --config=<file>` invocation driven directly against the locally built
|
||||
> binary: it printed the reconcile summary, `authority: file (<path>)`, and
|
||||
> `no changes` on the second start. The log lines quoted in step 3 come from
|
||||
> that run, with the paths and ports the container uses.
|
||||
|
||||
## 1. Pull and verify the image
|
||||
|
||||
```sh
|
||||
BASE=https://git.mial.net/mokhtar/nxdns
|
||||
VERSION=$(curl -fsS -o /dev/null -w '%{redirect_url}' "$BASE/releases/latest" |
|
||||
sed 's#.*/releases/tag/v##')
|
||||
docker pull git.mial.net/mokhtar/nxdns:$VERSION
|
||||
```
|
||||
|
||||
Pin a version. `:latest` exists and moves, which is what you want when you are trying it out and not what you want on a machine your household's DNS depends on. The lookup above asks the server for the current release rather than hardcoding a number that goes stale one release later — Gitea redirects `releases/latest` to the newest published release's tag page. To take a particular version instead, set `VERSION=<version>` yourself.
|
||||
|
||||
Verify what you pulled before you run it. The release publishes an `IMAGE-DIGEST.txt` asset naming the digest of the image index, and that file is covered by the signed `SHA256SUMS.txt`:
|
||||
|
||||
```sh
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/IMAGE-DIGEST.txt"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt.asc"
|
||||
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
|
||||
sha256sum -c --ignore-missing SHA256SUMS.txt
|
||||
docker buildx imagetools inspect git.mial.net/mokhtar/nxdns:$VERSION \
|
||||
--format '{{.Manifest.Digest}}'
|
||||
cut -d@ -f2 IMAGE-DIGEST.txt
|
||||
```
|
||||
|
||||
The last two have to print the same string — `IMAGE-DIGEST.txt` holds a whole pinned reference, `name:tag@sha256:…`, so the `cut` is what reduces it to the digest `imagetools` prints. [Verify a release](verify-a-release.md) covers the key, the fingerprint, every failure message, and what the signature does and does not prove.
|
||||
|
||||
> Verified on 2026-10-02 against `v0.0.21`, with an empty `DOCKER_CONFIG`, so no registry credentials: the lookup printed `0.0.21`, `docker pull` succeeded without a login, `gpg --verify` printed `Good signature` with the primary fingerprint above, `sha256sum -c` printed `OK` for all three files, and `imagetools inspect` and the `cut` both printed `sha256:ce1fef32c7ee6c23656abd94e53e4d4d6b1d34fe88a2c842b82c7202d8b904c3`.
|
||||
|
||||
## 2. Get the compose file and write the configuration
|
||||
|
||||
Every path on this page is relative to a checkout of the repository, because that is how it was verified. Running the published image needs no checkout, though — one file is enough. Fetch it for the version you pulled and work in its directory instead, dropping `deploy/docker/` from the paths below:
|
||||
## 1. Get the compose file
|
||||
|
||||
```sh
|
||||
mkdir -p ~/nxdns && cd ~/nxdns
|
||||
curl -fLO "$BASE/raw/tag/v$VERSION/deploy/docker/compose.yaml"
|
||||
curl -fLO https://git.mial.net/mokhtar/nxdns/raw/tag/v<version>/deploy/docker/compose.yaml
|
||||
```
|
||||
|
||||
> Verified on 2026-10-02: the `curl` returned `compose.yaml` from the `v0.0.21` tag with a 200.
|
||||
The compose file runs `git.mial.net/mokhtar/nxdns:<version>`, the release it was tagged with. It publishes ports 53 (UDP and TCP) and 8080, keeps the data directory in the volume `nxdns-data`, and mounts `./etc-nxdns` read-only as `/etc/nxdns`.
|
||||
|
||||
Compose bind-mounts `deploy/docker/etc-nxdns` read-only at `/etc/nxdns`. Create it and put the configuration in it:
|
||||
To check the image against the signed release before you run it, follow [Verify a release](verify-a-release.md#6-verify-the-container-image).
|
||||
|
||||
## 2. Write the configuration
|
||||
|
||||
```sh
|
||||
mkdir -p deploy/docker/etc-nxdns
|
||||
$EDITOR deploy/docker/etc-nxdns/config.zon
|
||||
mkdir -p etc-nxdns
|
||||
$EDITOR etc-nxdns/config.zon
|
||||
```
|
||||
|
||||
The smallest file that starts is one group named `default` and one enabled upstream:
|
||||
The smallest configuration that starts is a group named `default` and one upstream resolver, with a password for the web interface:
|
||||
|
||||
```zon
|
||||
.{
|
||||
@@ -77,160 +30,94 @@ The smallest file that starts is one group named `default` and one enabled upstr
|
||||
}
|
||||
```
|
||||
|
||||
**The compose file ships file mode**, with `command: ["run", "--config=/etc/nxdns/config.zon"]`. That file is the configuration: the container reconciles its database onto it at every start, and the admin interface answers 403 to configuration edits. To change anything, edit the file and restart the container. It also means a fresh or recreated `nxdns-data` volume rebuilds itself from the mounted file with no extra step.
|
||||
|
||||
The file is therefore required, and its absence is a hard failure rather than a start with defaults:
|
||||
|
||||
```
|
||||
FAIL /etc/nxdns/config.zon: no such file
|
||||
nxdns run failed: ManagedConfigUnreadable
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
A file that is present but rejected is a different failure with the same exit code. No `default` group, no enabled upstream, a syntax error — `run` prints the diagnostic and exits 2 as well. A file whose only group was named `other`:
|
||||
|
||||
```
|
||||
FAIL groups: no group named 'default'; every unknown client is assigned to it
|
||||
nxdns run failed: MissingDefaultGroup
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
Under `restart: unless-stopped` any of these is a restart loop — Docker has no start limit and will retry forever. Read the lines above the failure, which name the fault. See [Troubleshoot nxdns](troubleshoot.md).
|
||||
|
||||
### Database mode in Docker instead
|
||||
|
||||
Drop the `command:` line from `compose.yaml` and the container runs `nxdns run`, with the database as the configuration and the file read by nothing. On a fresh volume that database is empty and the container exits 2 with `NoUsableUpstreams`, so load it once before bringing the service up:
|
||||
The container runs as uid 65532 and cannot change the mounted files, so make the file readable by that uid and nobody else:
|
||||
|
||||
```sh
|
||||
docker compose -f deploy/docker/compose.yaml run --rm nxdns import /etc/nxdns/config.zon
|
||||
sudo chown 65532:65532 etc-nxdns/config.zon
|
||||
sudo chmod 0600 etc-nxdns/config.zon
|
||||
```
|
||||
|
||||
The file is positional; add `--allow-delete` when re-running it against a populated volume and the diff deletes rows. Without this step, `restart: unless-stopped` plus exit 2 is a crash loop with no way out.
|
||||
The compose file runs nxdns in file mode: this file is the configuration. Every start applies it, and the web interface refuses configuration changes and names the file instead. To change anything, edit the file and restart the container. A new or recreated `nxdns-data` volume rebuilds itself from the file.
|
||||
|
||||
> Not run in a container on this host, for the reason in the verification note
|
||||
> at the top: no image could be staged here. The `nxdns import <file>` and
|
||||
> `nxdns import <file> --allow-delete` commands inside it were run directly
|
||||
> against the locally built binary — the first applied an additive file and
|
||||
> exited 0, the second was required after a plain `import` refused a
|
||||
> row-deleting file with `DestructiveImport` and exited 2.
|
||||
|
||||
The container runs as uid 65532, and the mount is read-only, so the container cannot repair permissions itself. Mode 0644 works and was used here. If the file carries a secret — `web.password`, or a `web.password_hash` from a restored export — give it to that uid instead:
|
||||
## 3. Start it
|
||||
|
||||
```sh
|
||||
chown 65532:65532 deploy/docker/etc-nxdns/config.zon
|
||||
chmod 0600 deploy/docker/etc-nxdns/config.zon
|
||||
docker compose up -d
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
> Not verified on this host: `chown` to a uid you do not own needs root. What
|
||||
> was verified is the failure it prevents — a configuration file at 0600 owned
|
||||
> by another uid makes the container refuse to start and restart in a loop. In
|
||||
> file mode an unreadable file is a configuration fault:
|
||||
> `FAIL /etc/nxdns/config.zon: not readable` followed by
|
||||
> `nxdns run failed: ManagedConfigUnreadable`, exit 2. See
|
||||
> [Troubleshoot nxdns](troubleshoot.md).
|
||||
|
||||
## 3. Run it
|
||||
|
||||
```sh
|
||||
docker compose -f deploy/docker/compose.yaml up -d
|
||||
docker compose -f deploy/docker/compose.yaml logs -f
|
||||
```
|
||||
|
||||
`compose.yaml` names the release it was tagged with: its image is `${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-<release>}}`, and `zig build cut` writes `<release>` in the same commit that bumps `build.zig.zon`, so the file from the `v$VERSION` tag runs `$VERSION` with no variable set. Set `NXDNS_VERSION` to run a different release with the same file; set `NXDNS_IMAGE` to run something else entirely, which is what the build-from-source section at the bottom does. Compose files from `v0.0.22` and earlier default to `:latest` instead, so with one of those, set `NXDNS_VERSION=$VERSION` on every command.
|
||||
|
||||
> Verified on 2026-10-20 with `docker compose -f deploy/docker/compose.yaml
|
||||
> config` on a tree whose `build.zig.zon` declares `0.0.22`, which resolves
|
||||
> the variables without contacting a registry: no variables gives
|
||||
> `git.mial.net/mokhtar/nxdns:0.0.22`, `NXDNS_VERSION=0.0.21` gives
|
||||
> `git.mial.net/mokhtar/nxdns:0.0.21`, and `NXDNS_IMAGE=nxdns` gives `nxdns`.
|
||||
|
||||
Every block on this page runs from the repository root, and none of them change directory, so they can be pasted in order. `-f` is what makes that work: Compose resolves the relative paths inside `compose.yaml` — the `etc-nxdns` bind mount — against the directory holding the file, not against your shell, and it takes the project name `docker` from that directory either way, which is why the container is `docker-nxdns-1`.
|
||||
|
||||
A healthy first start logs the reconcile, the authority and the bound sockets:
|
||||
A healthy first start applies the file and names every socket it opened. Among its first lines:
|
||||
|
||||
```
|
||||
info(migrations): config.db migrated from schema version 0 to 1
|
||||
reconciled '/etc/nxdns/config.zon': upstreams +1 ~0 -0; settings +46 ~0 -0;
|
||||
settings keys changed: dns.bind_ipv4 dns.bind_ipv6 dns.port web.bind web.port …
|
||||
web authentication is now enabled
|
||||
info(nxdns): authority: file (/etc/nxdns/config.zon)
|
||||
info(nxdns): nxdns <version> serving on udp [::]:53 tcp [::]:53 tcp 0.0.0.0:53; 1 upstream(s); blocklist generation 1
|
||||
info(web_server): web interface listening on 0.0.0.0:8080
|
||||
```
|
||||
|
||||
Every later start on an unchanged file reports `reconciled '/etc/nxdns/config.zon': no changes` and writes nothing to the database.
|
||||
Later starts with an unchanged file log `reconciled '/etc/nxdns/config.zon': no changes`.
|
||||
|
||||
Confirm it answers and that the admin interface is up:
|
||||
If the file is missing, unreadable or invalid, nxdns prints what is wrong and exits 2, for example:
|
||||
|
||||
```
|
||||
FAIL groups: no group named 'default'; every unknown client is assigned to it
|
||||
nxdns run failed: MissingDefaultGroup
|
||||
```
|
||||
|
||||
With `restart: unless-stopped`, Docker then restarts the container until you fix the file, so read the log. If a host port is already in use, `docker compose up` fails with `address already in use`; free the port or change the `ports:` list. On a systemd host, port 53 is usually held by `systemd-resolved`; [Install with systemd](install-with-systemd.md#if-port-53-is-already-taken) shows how to free it.
|
||||
|
||||
## 4. Check it and point your network at it
|
||||
|
||||
```sh
|
||||
dig @127.0.0.1 example.com A +short
|
||||
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/
|
||||
```
|
||||
|
||||
> Verified on 2026-10-02 with the pulled `v0.0.21` image, the configuration above and the unchanged `compose.yaml`, on host ports 53 and 8080: the first start logged the lines above, `dig` returned the A records for `example.com`, `curl` returned 200, and `/api/health` reported `"status":"ok"` with one of one upstreams available. `docker compose up -d` fails with `failed to bind host port 0.0.0.0:8080/tcp: address already in use` when a host port is occupied; free the port or edit the `ports:` list.
|
||||
Open `http://<host-ip>:8080` and log in. The interface shows everything nxdns does; in file mode its configuration pages are read-only and name the file to edit.
|
||||
|
||||
The compose file publishes 53/udp, 53/tcp and 8080, keeps `/var/lib/nxdns` in the named volume `nxdns-data`, and sets the per-namespace sysctl `net.ipv4.ip_unprivileged_port_start=0` so uid 65532 can bind port 53 without any capability. Uncomment the 443 and 853 mappings when you enable the DoH or DoT listener; see [Enable DoH and DoT](enable-doh-and-dot.md).
|
||||
Blocklists go in the file too. Add a source and attach it to the `default` group, then restart:
|
||||
|
||||
## 4. Do not point the host at the container
|
||||
|
||||
The container resolves its own upstream DoH and DoT hostnames through the host's DNS configuration. If you set the host's `/etc/resolv.conf` to the nxdns container, the container's startup lookups depend on the service that is trying to start. Point LAN clients at nxdns; leave the container's host on its own resolver.
|
||||
|
||||
## Raspberry Pi 5
|
||||
|
||||
Nothing changes. The published tag is a multi-architecture index, so `docker pull` on the Pi selects the `linux/arm64` image on its own. The platform list is one of the things [Verify a release](verify-a-release.md) has you check.
|
||||
|
||||
To pull the arm64 image from an x86_64 machine — to inspect it, or to save and copy it — name the platform:
|
||||
```zon
|
||||
.blocklist_sources = .{
|
||||
.{ .url = "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts", .name = "StevenBlack hosts" },
|
||||
},
|
||||
.group_sources = .{
|
||||
.{ .group = "default", .source_url = "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts" },
|
||||
},
|
||||
```
|
||||
|
||||
```sh
|
||||
docker pull --platform linux/arm64 git.mial.net/mokhtar/nxdns:$VERSION
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
> Verified on 2026-10-02 against `v0.0.21`: `imagetools inspect` lists `linux/amd64` and `linux/arm64`, and the pull above fetched an image whose `docker image inspect` reports `linux/arm64`. It was not started: this host is x86_64 with no emulation.
|
||||
The restart logs the change and then the download:
|
||||
|
||||
## Build the image from source instead
|
||||
```
|
||||
reconciled '/etc/nxdns/config.zon': sources +1 ~0 -0; group_sources +1 ~0 -0;
|
||||
info(blocklist_manager): blocklist snapshot generation 3: 1 of 1 sources loaded, 1997188 bytes
|
||||
```
|
||||
|
||||
The Dockerfile does not compile anything. It assembles a filesystem around binaries you build first, so build the admin interface and the release artifacts from the repository root:
|
||||
The [configuration reference](../reference/configuration.md#lists) lists everything else the file can hold: more groups, devices, rules and local records.
|
||||
|
||||
To make every device use nxdns, set the DNS server your router hands out (its DHCP settings) to the Docker host's address. Leave the Docker host itself on another resolver: the container looks up its upstreams' names through the host, and that should not depend on the container already running.
|
||||
|
||||
## Database mode instead
|
||||
|
||||
To change settings in the web interface rather than in the file, delete the `command:` line from `compose.yaml`. The database in the volume is then the configuration and the file is not read. Load the file into the empty database once, then start:
|
||||
|
||||
```sh
|
||||
(cd admin && npm ci && npm run build)
|
||||
VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
|
||||
zig build dist -Dversion-string="$VERSION" \
|
||||
-Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
|
||||
DOCKER_BUILDKIT=1 docker build -t nxdns -f deploy/docker/Dockerfile .
|
||||
docker compose run --rm nxdns import /etc/nxdns/config.zon
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Take the version from `build.zig.zon` rather than inventing one: `verify-dist` asserts the two agree, so a made-up string builds but fails verification. BuildKit is required — the Dockerfile pins its builder stage to `$BUILDPLATFORM`, which the classic builder does not define.
|
||||
Without that import the empty database has no upstream, and the container exits 2 with `NoUsableUpstreams`.
|
||||
|
||||
Build `admin/dist` every time, before the binaries. A stale bundle is embedded silently and ships an admin interface that does not match its API — which is why `dist` refuses to build against the `admin/dist-placeholder` default at all.
|
||||
## Run another release
|
||||
|
||||
The context has to be the repository root, because the Dockerfile copies `zig-out/dist/bin` and `zig-out/dist/stage`. The result is a `scratch` image holding the binary, a CA bundle, `/LICENSE`, `/THIRD-PARTY-NOTICES` and two empty directories.
|
||||
|
||||
Run that image instead of the published one by naming it:
|
||||
`NXDNS_VERSION` overrides the release the compose file names:
|
||||
|
||||
```sh
|
||||
NXDNS_IMAGE=nxdns docker compose -f deploy/docker/compose.yaml up -d
|
||||
NXDNS_VERSION=<version> docker compose up -d
|
||||
```
|
||||
|
||||
For an arm64 image on an x86_64 machine, use buildx. The Dockerfile's builder stage is pinned to `$BUILDPLATFORM` and only copies files, so no emulation is involved:
|
||||
|
||||
```sh
|
||||
docker buildx build --platform linux/arm64 -t nxdns:arm64 -f deploy/docker/Dockerfile .
|
||||
```
|
||||
|
||||
Add `--push` or `--load` to keep the result; the default buildx driver leaves it in the build cache.
|
||||
|
||||
> Verified on this host, except the two buildx lines. `zig build dist` was run
|
||||
> to completion with the version read out of `build.zig.zon` and exited 0, and
|
||||
> the `DOCKER_BUILDKIT=1 docker build` above was then run against that
|
||||
> `zig-out/dist` tree and exited 0. The binary copied out of the resulting
|
||||
> image with `docker cp` hashed identically to
|
||||
> `zig-out/dist/stage/nxdns-<version>-x86_64-linux-musl/nxdns`. The
|
||||
> `NXDNS_IMAGE=nxdns docker compose ... up -d` line was verified as described in
|
||||
> step 3, with the host ports moved. `docker buildx build --platform
|
||||
> linux/arm64` was run here too and exited 0 on an x86_64 host with no
|
||||
> emulation available — the builder stage is pinned to `$BUILDPLATFORM` and the
|
||||
> final stage is `FROM scratch`, so nothing arm64 ever executes during the
|
||||
> build. It printed the driver's `No output specified` warning, which is the
|
||||
> reason the paragraph above tells you to add `--push` or `--load`. See
|
||||
> [Install with systemd](install-with-systemd.md#build-from-source-instead) for
|
||||
> the `dist` and `verify-dist` detail.
|
||||
To move to a new release, see [Upgrade](upgrade.md#docker).
|
||||
|
||||
@@ -1,52 +1,33 @@
|
||||
# Install nxdns with Nix
|
||||
# Install with Nix
|
||||
|
||||
Adds nxdns to a NixOS machine as a flake input pinned to a release tag and runs it with the flake's `services.nxdns` module. At the end the machine serves DNS on port 53 from a configuration file that the pinned binary checked at build time, and a Renovate custom manager opens a pull request when a new tag appears.
|
||||
Add nxdns to a NixOS machine as a flake input pinned to a release, and run it with the flake's `services.nxdns` module. At the end the machine answers DNS on port 53 from a configuration file that was checked when the system was built.
|
||||
|
||||
nxdns publishes its own `flake.nix`. Its packages do not build nxdns from source: each one fetches the release tarball for the target and pins its SHA-256 hash, so a changed byte fails the build. The two supported systems are `aarch64-linux` and `x86_64-linux`, both static musl builds that need nothing on the host.
|
||||
The flake does not build nxdns from source. Its package fetches the release tarball for `x86_64-linux` or `aarch64-linux` and pins its SHA-256, so a changed byte fails the build.
|
||||
|
||||
For the signature and checksum checks a human does once, see [verify a release](verify-a-release.md). For what each configuration field means, see [the configuration reference](../reference/configuration.md).
|
||||
## 1. Add the input
|
||||
|
||||
> Verification: the commands in step 1 and step 2 were run on the machine that wrote this page, against the flake at nxdns 0.0.16. `nix flake check --no-build` passed and `nix build` produced a binary that printed `nxdns 0.0.16`. Step 3 was verified on 2026-10-20 by the flake's own checks, built with Nix 2.35.3 on an x86_64 host with KVM and the module running the 0.0.22 release: `checks.x86_64-linux.nixos-module` boots a NixOS VM with the module and `openFirewall`, gets `nas.lan` from `dig @127.0.0.1`, finds the packaged unit with its drop-in in `systemctl cat`, finds port 53 open over UDP and TCP, and switches to a configuration-only change that restarts the service and changes the answer; `checks.x86_64-linux.nixos-module-rejects-config` fails a system build on a bad regex with `FAIL rules[0].pattern: '(' is not a valid regex pattern`. The Renovate snippet in step 4 is copied from the shape `rpi.mial.net` already uses for another flake input of the same author.
|
||||
|
||||
## 1. Add the input, pinned to a tag
|
||||
|
||||
In the consuming flake:
|
||||
In your flake:
|
||||
|
||||
```nix
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
|
||||
nxdns = {
|
||||
url = "git+https://git.mial.net/mokhtar/nxdns.git?ref=refs/tags/v0.0.16";
|
||||
url = "git+https://git.mial.net/mokhtar/nxdns.git?ref=refs/tags/v<version>";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Pin a tag, not a branch. A branch pin moves the version under you at the next `nix flake update`, and the hashes in the flake belong to whatever release that branch last cut.
|
||||
|
||||
The `follows` line is not cosmetic. Without it Nix fetches and evaluates nxdns's own nixpkgs as a second nixpkgs, which costs a download and an evaluation for a package that only needs `stdenv`, `fetchurl`, and `lib`.
|
||||
|
||||
Write the lock entry:
|
||||
Pin a tag, not a branch: a tag never moves under you. The `follows` line saves fetching and evaluating a second nixpkgs. Then write the lock entry:
|
||||
|
||||
```sh
|
||||
nix flake lock
|
||||
```
|
||||
|
||||
## 2. Check what you pinned
|
||||
## 2. Enable the service
|
||||
|
||||
```sh
|
||||
nix flake check --no-build
|
||||
nix eval .#packages.x86_64-linux.default.outPath
|
||||
```
|
||||
|
||||
Evaluation does not fetch the tarball. The download happens at build time, and the hash in nxdns's flake is what the build asserts the bytes against.
|
||||
|
||||
## 3. Run the service
|
||||
|
||||
`nixosModules.default` exists from the first release after `v0.0.22`; pin that tag or a later one. A tag up to `v0.0.22` has the package only.
|
||||
|
||||
Write the configuration next to the NixOS configuration that uses it. The smallest file that starts is one group named `default` and one enabled upstream:
|
||||
Write the configuration next to your NixOS configuration, for example as `nxdns-config.zon`. The smallest one that starts is a group named `default` and one upstream resolver:
|
||||
|
||||
```zon
|
||||
.{
|
||||
@@ -55,7 +36,7 @@ Write the configuration next to the NixOS configuration that uses it. The smalle
|
||||
}
|
||||
```
|
||||
|
||||
Pass the flake inputs to the module system, import the module, and enable it:
|
||||
Import the module and enable it:
|
||||
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
@@ -70,34 +51,41 @@ Pass the flake inputs to the module system, import the module, and enable it:
|
||||
}
|
||||
```
|
||||
|
||||
Then `nixos-rebuild switch`. The module has four options:
|
||||
Then run `nixos-rebuild switch`.
|
||||
|
||||
| Option | Default | What it does |
|
||||
| --- | --- | --- |
|
||||
| `enable` | `false` | Runs nxdns as `nxdns.service`, as the `nxdns` system user. |
|
||||
| `package` | the release of the pinned tag | The nxdns release to run. |
|
||||
| `configFile` | none, required | The configuration, in ZON. It is installed at `/etc/nxdns/config.zon`. |
|
||||
| `openFirewall` | `false` | Opens port 53 over UDP and TCP. The web interface on port 8080 and the DoH and DoT ports stay closed; open them yourself if you want them reachable from the network. |
|
||||
| `configFile` | none, required | The configuration, installed as `/etc/nxdns/config.zon`. |
|
||||
| `openFirewall` | `false` | Opens port 53 over UDP and TCP. The web interface (8080) and the DoH and DoT ports stay closed; open them yourself if other machines should reach them. |
|
||||
|
||||
`configFile` is copied into the Nix store, which every local user can read. Do not put a plaintext `web.password` in it: put the `web.password_hash` from an export there instead, as [set up admin authentication](set-up-admin-authentication.md) describes.
|
||||
`configFile` is copied into the Nix store, which every local user can read. Do not put a plaintext `web.password` in it. Use the `web.password_hash` from an export instead, as [Set up admin authentication](set-up-admin-authentication.md#put-a-hash-in-the-file-instead) shows.
|
||||
|
||||
What the module does with them:
|
||||
What the module does:
|
||||
|
||||
- **The build checks the configuration.** `nxdns import` from the pinned `package` reads `configFile` into a throwaway database during the build. A file that `import` rejects, because it does not parse, breaks a field rule or does not reconcile, fails `nixos-rebuild` with the binary's own reason, as in `FAIL rules[0].pattern: ...`, and nothing is deployed. `nxdns check` is not used, because it queries every upstream and the build sandbox has no network. So the build does not load the DoH and DoT certificate and key files, and does not reach the upstreams: a missing certificate still stops the service at start. The build also says nothing about the database already on the machine; see the rollback note below.
|
||||
- **nxdns runs in file mode.** The service runs `nxdns run --config=/etc/nxdns/config.zon`: every start reconciles the database onto the file, and the web interface refuses configuration edits. Change the file and switch to change anything. A switch that changes only the configuration restarts the service.
|
||||
- **The unit is the packaged one.** The package installs `deploy/systemd/nxdns.service` from the release tarball, with its sandboxing and its `RestartPreventExitStatus=2 64`, and the module adds a drop-in that changes only the command line and leaves `/etc/nxdns` to NixOS. `systemctl cat nxdns.service` shows both.
|
||||
- **The build checks the configuration.** The pinned nxdns loads `configFile` into a throwaway database during the build, so a file nxdns would reject fails `nixos-rebuild` with nxdns's own message, for example `FAIL rules[0].pattern: '(' is not a valid regex pattern`, and nothing is deployed. The build has no network, so it cannot check that the upstreams answer or load DoH and DoT certificates; a missing certificate still stops the service when it starts.
|
||||
- **nxdns runs in file mode.** Every start applies the file, and the web interface shows the configuration read-only. To change anything, change the file and switch. A switch that changes only the configuration restarts the service.
|
||||
- **The unit is the packaged one**, with its sandboxing. The module only replaces its command line; `systemctl cat nxdns.service` shows both.
|
||||
|
||||
The module does not touch the machine's own resolver. If you point `networking.nameservers` at `127.0.0.1`, the machine loses name resolution whenever nxdns is down, including while you repair it; a resolver outside the machine avoids that.
|
||||
The module does not touch the machine's own resolver. Point your network at nxdns by setting the DNS server your router hands out to this machine's address, and leave `networking.nameservers` on another resolver, so the machine can still resolve names while nxdns is down.
|
||||
|
||||
**Rolling back.** A `nixos-rebuild --rollback` or an older generation puts an older binary in front of a database that the newer one may have migrated. That binary refuses the database with `SchemaTooNew`, exit 2, and the unit stops instead of restarting. [Upgrade](upgrade.md#what-happens-to-the-database) describes the recovery.
|
||||
The package alone is `inputs.nxdns.packages.${pkgs.stdenv.hostPlatform.system}.default`, for running nxdns some other way. It installs `bin/nxdns` and `lib/systemd/system/nxdns.service`, and sets `meta.mainProgram`.
|
||||
|
||||
The package alone is also available, for a machine that runs nxdns some other way: `inputs.nxdns.packages.${pkgs.stdenv.hostPlatform.system}.default` installs `bin/nxdns`, `lib/systemd/system/nxdns.service`, and `LICENSE` and `THIRD-PARTY-NOTICES` under `share/doc/nxdns`. It sets `meta.mainProgram`, so `lib.getExe` resolves to the binary.
|
||||
## 3. Upgrade
|
||||
|
||||
## 4. Let Renovate bump the tag
|
||||
Read the release notes, change the tag in the input URL, then:
|
||||
|
||||
Renovate's built-in `nix` manager does not do this. It only advances `flake.lock` along the ref an input already tracks, and a `refs/tags/vX.Y.Z` ref never moves, so it reports no releases for a tag-pinned input. Verified on 2026-09-09 with Renovate 42.99.0 against a Gitea host: all flake inputs, GitHub-hosted ones included, came back with an empty release list.
|
||||
```sh
|
||||
nix flake lock --update-input nxdns
|
||||
nixos-rebuild switch
|
||||
```
|
||||
|
||||
What works is a regex custom manager that treats the tag in the input URL as a version string, with the `gitea-tags` datasource:
|
||||
Rolling back to an older generation puts an older nxdns in front of a database the newer one may already have upgraded. The older binary then refuses to start; [Upgrade](upgrade.md#going-back-to-an-older-release) explains the way back.
|
||||
|
||||
## Let Renovate bump the tag
|
||||
|
||||
Renovate's built-in `nix` manager cannot do this: it only moves `flake.lock` along the ref an input already follows, and a tag ref never moves. A regex custom manager that reads the tag from the input URL, with the `gitea-tags` datasource, does:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -117,10 +105,6 @@ What works is a regex custom manager that treats the tag in the input URL as a v
|
||||
}
|
||||
```
|
||||
|
||||
Verified on 2026-09-09: with this manager, Renovate opened the pull request for v0.0.18 on the day of the tag. That pull request rewrites the tag in `flake.nix` only. `flake.lock` still records the old revision, so the same pull request must also refresh the lock, either with a `postUpgradeTasks` command (`nix flake update nxdns`, which needs the self-hosted `allowedCommands` setting) or with a CI job on the Renovate branch that commits the lock. The datasource proposes only tags that already exist, so it never pins a release that has not been cut.
|
||||
Its pull request changes the tag in `flake.nix` only. The same pull request also needs a refreshed `flake.lock`: run `nix flake update nxdns` as a `postUpgradeTasks` command (self-hosted Renovate, with `allowedCommands`), or have CI commit the lock on the Renovate branch.
|
||||
|
||||
Between the tag push and the asset upload there is a window in which the tag exists and the release tarballs do not. A pin written by hand during that window evaluates, then fails at build time with a 404 from the release download URL. Wait for the release to be published, or re-run the build once it is. Renovate's own pull requests are not affected by the window in practice, because it runs on a schedule rather than on the tag push.
|
||||
|
||||
## Upgrading
|
||||
|
||||
Change the `?ref=refs/tags/vX.Y.Z` in the input, run `nix flake lock --update-input nxdns`, and rebuild. Read the release notes first: nxdns is pre-0.1 and breaks on purpose, and [upgrade](upgrade.md) lists what state a version change touches.
|
||||
A tag can exist for a short while before its release files are uploaded. A pin made by hand in that window fails the build with a 404 from the download URL; build again once the release is published.
|
||||
|
||||
@@ -1,125 +1,44 @@
|
||||
# Install nxdns with systemd
|
||||
# Install with systemd
|
||||
|
||||
Installs nxdns as a system service on a Linux host with systemd, including a Raspberry Pi 5. At the end the service answers DNS on port 53 and starts on boot.
|
||||
|
||||
The normal path is to download a released tarball, verify it, and install what is inside it. Building from source is still supported and is the last section of this page.
|
||||
|
||||
For what each flag does, see [the CLI reference](../reference/cli.md); for what each configuration field means, see [the configuration reference](../reference/configuration.md).
|
||||
|
||||
> Verification: `systemd-analyze verify` was run on the machine that wrote this
|
||||
> page. `nxdns check`, `nxdns import`, `nxdns export` and `nxdns run` were run
|
||||
> there too, but against a scratch `--data-dir` and `--config` on an
|
||||
> unprivileged port, because that machine is not a deploy target and has no
|
||||
> `/etc/nxdns`, no `/var/lib/nxdns` and no root. The steps that need root on a
|
||||
> target host — `install`, `systemd-sysusers`, `systemctl` — were not run; they
|
||||
> are marked where they appear.
|
||||
>
|
||||
> The download in step 1 was run on 2026-10-02 against the published `v0.0.21` release; its note carries the detail.
|
||||
>
|
||||
> The `zig build dist` and `zig build verify-dist` blocks in the last section
|
||||
> were run here, both to completion and both exiting 0; that section carries
|
||||
> the detail.
|
||||
Install nxdns as a system service on a Linux machine with systemd, including a Raspberry Pi. At the end it answers DNS on port 53 for your network and starts on boot.
|
||||
|
||||
## 1. Download and verify
|
||||
|
||||
Two static musl tarballs are published per release, one per architecture. Pick `x86_64-linux-musl` for a normal PC or server and `aarch64-linux-musl` for a Raspberry Pi 5.
|
||||
Each release has two builds: `x86_64-linux-musl` for a PC or server, and `aarch64-linux-musl` for a Raspberry Pi or another 64-bit ARM machine. Both are static binaries that need nothing installed. On the machine that will run nxdns:
|
||||
|
||||
```sh
|
||||
BASE=https://git.mial.net/mokhtar/nxdns
|
||||
VERSION=$(curl -fsS -o /dev/null -w '%{redirect_url}' "$BASE/releases/latest" |
|
||||
sed 's#.*/releases/tag/v##')
|
||||
mkdir -p ~/nxdns-release && cd ~/nxdns-release
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/nxdns-$VERSION-x86_64-linux-musl.tar.gz"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt.asc"
|
||||
```
|
||||
|
||||
The first line asks the server which release is current instead of hardcoding a number that goes stale one release later — Gitea redirects `releases/latest` to the newest published release's tag page. To install a particular version instead, set `VERSION=<version>` yourself with the one you want; the tarball filenames carry the version either way, so there is no version-free download URL for them.
|
||||
|
||||
Verify before you extract. The signature is over `SHA256SUMS.txt`, and `SHA256SUMS.txt` is over the tarballs:
|
||||
|
||||
```sh
|
||||
curl -fLO https://git.mial.net/mokhtar/nxdns/releases/download/v<version>/nxdns-<version>-x86_64-linux-musl.tar.gz
|
||||
curl -fLO https://git.mial.net/mokhtar/nxdns/releases/download/v<version>/SHA256SUMS.txt
|
||||
curl -fLO https://git.mial.net/mokhtar/nxdns/releases/download/v<version>/SHA256SUMS.txt.asc
|
||||
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
|
||||
sha256sum -c --ignore-missing SHA256SUMS.txt
|
||||
tar -xzf "nxdns-$VERSION-x86_64-linux-musl.tar.gz"
|
||||
tar -xzf nxdns-<version>-x86_64-linux-musl.tar.gz
|
||||
cd nxdns-<version>-x86_64-linux-musl
|
||||
```
|
||||
|
||||
[Verify a release](verify-a-release.md) has the whole procedure: where the public key comes from, what fingerprint to expect, what each failure means, and what the signature does and does not prove. Read it once before your first install.
|
||||
The signature covers `SHA256SUMS.txt`, and `SHA256SUMS.txt` covers the tarball. [Verify a release](verify-a-release.md) explains where the public key comes from and which fingerprint to expect; read it before your first install.
|
||||
|
||||
The extracted directory `nxdns-$VERSION-x86_64-linux-musl/` holds everything this page installs:
|
||||
The directory holds the binary `nxdns`, the systemd unit `nxdns.service`, the sysusers file `nxdns.conf` that creates the `nxdns` user, the licences and a short `INSTALL.md`.
|
||||
|
||||
| File | What it is |
|
||||
| --- | --- |
|
||||
| `nxdns` | The static binary, mode 0755 |
|
||||
| `nxdns.service` | The systemd unit |
|
||||
| `nxdns.conf` | The sysusers fragment that creates the `nxdns` user |
|
||||
| `LICENSE` | EUPL-1.2 |
|
||||
| `THIRD-PARTY-NOTICES` | Licences of everything compiled or bundled in |
|
||||
| `INSTALL.md` | A short version of this page |
|
||||
## 2. Install the binary, the user and the unit
|
||||
|
||||
> Verified on 2026-10-02 against `v0.0.21`, from a clean directory with a clean `GNUPGHOME` holding only the key from keys.openpgp.org: the lookup printed `0.0.21`, `gpg --verify` printed `Good signature` over primary fingerprint `A206 1F6A B24D F2C0 E923 46FD 1509 B549 46D0 8A95`, `sha256sum -c` printed `OK` for both tarballs and `IMAGE-DIGEST.txt`, and the extracted directory held the six files in the table below at the modes given, with `./nxdns version` printing `nxdns 0.0.21`.
|
||||
|
||||
## 2. Copy the files to the target
|
||||
As root:
|
||||
|
||||
```sh
|
||||
cd "nxdns-$VERSION-x86_64-linux-musl"
|
||||
scp nxdns nxdns.service nxdns.conf target:/tmp/
|
||||
```
|
||||
|
||||
For a Raspberry Pi 5, extract the `aarch64-linux-musl` tarball instead — see [Raspberry Pi 5](#raspberry-pi-5) below.
|
||||
|
||||
> Not verified on this host: `target` is a placeholder for your server's
|
||||
> hostname, and the machine that wrote this page has no second host to copy
|
||||
> to.
|
||||
|
||||
Before copying, you can confirm the unit file parses:
|
||||
|
||||
```sh
|
||||
systemd-analyze verify nxdns.service
|
||||
```
|
||||
|
||||
Off the target host this prints one complaint and exits 1:
|
||||
|
||||
```
|
||||
nxdns.service: Command /usr/local/bin/nxdns is not executable: No such file or directory
|
||||
```
|
||||
|
||||
That is the ExecStart path check finding no binary yet. Any other message is a real problem with the unit. On the target, after step 3, the same command should print nothing.
|
||||
|
||||
> Verified on this host against `deploy/systemd/nxdns.service` in a checkout,
|
||||
> which is the same file the tarball ships — the path is the only difference.
|
||||
|
||||
## 3. Install the binary, the user and the unit
|
||||
|
||||
Run as root on the target:
|
||||
|
||||
```sh
|
||||
install -m 0755 /tmp/nxdns /usr/local/bin/nxdns
|
||||
|
||||
install -m 0644 /tmp/nxdns.conf /usr/lib/sysusers.d/nxdns.conf
|
||||
install -m 0755 nxdns /usr/local/bin/nxdns
|
||||
install -m 0644 nxdns.conf /usr/lib/sysusers.d/nxdns.conf
|
||||
systemd-sysusers
|
||||
|
||||
install -m 0644 /tmp/nxdns.service /etc/systemd/system/nxdns.service
|
||||
install -m 0644 nxdns.service /etc/systemd/system/nxdns.service
|
||||
systemctl daemon-reload
|
||||
|
||||
mkdir -p -m 0755 /etc/nxdns
|
||||
```
|
||||
|
||||
The sysusers fragment ships under the name it is installed as, so there is no rename to get wrong.
|
||||
Do not create `/var/lib/nxdns` or `/var/log/nxdns`. systemd creates them on the first start, with the right owner and modes.
|
||||
|
||||
> Not verified on this host: these commands need root on a target machine. The
|
||||
> files they install were read at HEAD and the unit was checked with
|
||||
> `systemd-analyze verify`.
|
||||
## 3. Write the configuration
|
||||
|
||||
The service user is a static one, not `DynamicUser`: a TLS key for the DoH or DoT listener has to be chown-able to a uid that survives a restart.
|
||||
|
||||
Do not create `/var/lib/nxdns` or `/var/log/nxdns` by hand. The unit's `StateDirectory` and `LogsDirectory` settings make systemd create them on first start, `/var/lib/nxdns` at mode 0700 owned by `nxdns`.
|
||||
|
||||
`/etc/nxdns` is the one directory the `mkdir` above is for. The unit's `ConfigurationDirectory=nxdns` also creates it, but not until the first start in step 5, and step 4 has to write a file into it before then. systemd does not mind finding the directory already there; it adjusts the mode and ownership to what the unit asks for.
|
||||
|
||||
## 4. Write the configuration
|
||||
|
||||
nxdns will not start with nothing to forward to. Write `/etc/nxdns/config.zon`. The smallest file that starts is one group named `default` and one enabled upstream:
|
||||
The smallest configuration that starts is a group named `default` and one upstream resolver. Write `/etc/nxdns/config.zon` and give the web interface a password:
|
||||
|
||||
```zon
|
||||
.{
|
||||
@@ -129,135 +48,99 @@ nxdns will not start with nothing to forward to. Write `/etc/nxdns/config.zon`.
|
||||
}
|
||||
```
|
||||
|
||||
That file holds a password in plain text, so restrict it as soon as you have written it:
|
||||
The file holds a password in plain text, so restrict it:
|
||||
|
||||
```sh
|
||||
chown root:nxdns /etc/nxdns/config.zon
|
||||
chmod 0640 /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
Root's umask is 022 on most distributions, so a freshly written `/etc/nxdns/config.zon` is mode 0644 and every account on the host can read the password out of it. The unit's `UMask=0077` does not help here: it applies to files the service creates once it is running, and never re-chmods a file that was written before the first start.
|
||||
|
||||
0640 with group `nxdns` rather than 0600: `/etc/nxdns` is a `ConfigurationDirectory`, which systemd leaves owned by root, and the service runs as `nxdns`. A root-owned 0600 file would be unreadable to it.
|
||||
|
||||
Keep that group read bit for good, not just for the first boot. Under `run --config` the service reads this file on **every** start, so tightening the mode later breaks the next restart. Under database authority it is `nxdns import` that reads the file, as whoever runs that command, and a bare `nxdns run` never reads it at all.
|
||||
|
||||
Do not expect `nxdns check` to catch a permissive mode here. Its only permission warning is for a TLS private key (`WARN doh_server.key_path: ... is mode 644; a TLS key must be readable by its owner only`, from `checkTlsFiles` in `src/cli.zig`); it never stats the configuration file. A mode 0644 `config.zon` passes `check` in silence, so the `chmod` above is yours to remember.
|
||||
|
||||
Check it before you start the service:
|
||||
Check it, then load it into the database:
|
||||
|
||||
```sh
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
nxdns import /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
A good file prints the source it checked, one `OK` line per upstream, and `OK: no problems found`:
|
||||
|
||||
```
|
||||
checking configuration file /etc/nxdns/config.zon
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
OK: no problems found
|
||||
```
|
||||
|
||||
The upstream probe sends a real query, so this needs working DNS on the host at the time you run it. Exit 2 means `check` found something to fix and printed every problem it found, not only the first.
|
||||
|
||||
Now load it into the database:
|
||||
|
||||
```sh
|
||||
nxdns import /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
```
|
||||
info(migrations): config.db migrated from schema version 0 to 1
|
||||
imported /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
The plaintext password is hashed into `web.password_hash` and never stored as plaintext; `nxdns export` writes `.password = null` beside the hash. Nothing downstream reads the plaintext again, so once step 6 confirms you can log in you can delete the file:
|
||||
`check` sends one real query through each upstream, so the machine needs working DNS when you run it. If it finds a problem it lists every one and exits 2.
|
||||
|
||||
The password is stored only as a hash, so once you have logged in (step 5) you can delete the file:
|
||||
|
||||
```sh
|
||||
rm /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
A kept file is not a backup — `nxdns export` is (see [Back up and restore](back-up-and-restore.md)), and the export carries the password hash rather than the password. If you keep it, leave it at 0640 root:nxdns.
|
||||
From now on you change settings in the web interface. This is database mode, and it is what the packaged unit runs. To keep `config.zon` in git as the configuration instead, keep the file and see [Run in file mode](#run-in-file-mode).
|
||||
|
||||
That is the **database mode** install, which is what the packaged unit runs: `ExecStart=/usr/local/bin/nxdns run`, no `--config`, so nothing reads a file after this step. Change settings afterwards through the admin interface, the API, or an export–edit–import cycle.
|
||||
|
||||
If you would rather keep `/etc/nxdns/config.zon` in git and have every restart converge onto it, do not delete the file — go to [Run in file mode](#run-in-file-mode) instead, and skip the `rm`.
|
||||
|
||||
> Verified on this host, with a scratch `--config` and `--data-dir` in place of
|
||||
> `/etc/nxdns` and `/var/lib/nxdns` — those two paths are the only difference
|
||||
> from the blocks above. A file written under umask 022 came out 0644,
|
||||
> `nxdns check --config` on it printed `OK: no problems found` with no mode
|
||||
> warning, `nxdns import` of it printed the migration line and `imported <path>`
|
||||
> and exited 0, and a following `nxdns export` wrote `.password = null` next to
|
||||
> a populated `.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…"`. The
|
||||
> `chown`, `chmod` and `rm` lines are ordinary root-owned-file operations and
|
||||
> were not run against a real `/etc/nxdns`, which this host does not have.
|
||||
|
||||
## 5. Start it
|
||||
## 4. Start it
|
||||
|
||||
```sh
|
||||
systemctl enable --now nxdns
|
||||
journalctl -u nxdns -f
|
||||
```
|
||||
|
||||
> Not verified on this host: needs root and an installed unit.
|
||||
|
||||
A healthy start logs a line naming every socket it bound:
|
||||
A healthy start names every socket it opened:
|
||||
|
||||
```
|
||||
info(nxdns): nxdns <version> serving on udp [::]:53 tcp [::]:53 tcp 0.0.0.0:53; 1 upstream(s); blocklist generation 1
|
||||
```
|
||||
|
||||
nxdns writes to stderr and systemd captures that into the journal; logging needs no further configuration. Port 53 is privileged, and the unit grants `CAP_NET_BIND_SERVICE` through `AmbientCapabilities`.
|
||||
The unit grants the capability to bind port 53 and runs nxdns as the `nxdns` user. It does not restart nxdns after exit code 2 (a configuration problem) or 64 (a wrong command line), because a retry cannot fix either; the journal says what is wrong. Fix it and start the service again.
|
||||
|
||||
The unit does not restart the service after exit 2 or exit 64 (`RestartPreventExitStatus=2 64`). Those are a wrong configuration and a wrong command line, and neither clears on a retry — restarting every two seconds until `StartLimitBurst` gives up would only bury the diagnostics that are already in the journal. `systemctl status nxdns` shows the failed state; fix the cause and start it again.
|
||||
### If port 53 is already taken
|
||||
|
||||
If the start fails, read [Troubleshoot nxdns](troubleshoot.md). The two common first-install failures are a port 53 already held by `systemd-resolved` and a configuration file that does not parse.
|
||||
```
|
||||
cannot bind udp [::1]:53: AddressInUse
|
||||
nxdns run failed: AddressInUse
|
||||
```
|
||||
|
||||
## 6. Confirm it answers
|
||||
On most systemd distributions `systemd-resolved` holds port 53 with its stub listener. Turn the stub off and keep resolved for the machine's own lookups:
|
||||
|
||||
From another machine on the LAN:
|
||||
```sh
|
||||
mkdir -p /etc/systemd/resolved.conf.d
|
||||
printf '[Resolve]\nDNSStubListener=no\n' > /etc/systemd/resolved.conf.d/nxdns.conf
|
||||
systemctl restart systemd-resolved
|
||||
```
|
||||
|
||||
If `/etc/resolv.conf` is a link to `/run/systemd/resolve/stub-resolv.conf`, point it at `/run/systemd/resolve/resolv.conf` so the machine still resolves names. `ss -lnup 'sport = :53'` shows what else holds the port.
|
||||
|
||||
## 5. Check it and point your network at it
|
||||
|
||||
From another machine on your network:
|
||||
|
||||
```sh
|
||||
dig @<server-ip> example.com A +short
|
||||
```
|
||||
|
||||
The admin interface is on port 8080 by default; log in with the password from the configuration file. `http://<server-ip>:8080/api/health` reports upstream availability and disk state without a login.
|
||||
Open `http://<server-ip>:8080` and log in with the password from step 3. Then add blocklists on the **Protection** page, as [Get started](../tutorial/get-started.md#5-add-a-blocklist) shows.
|
||||
|
||||
> Not verified on this host as written: `<server-ip>` is a placeholder, and a
|
||||
> LAN client to run it from is a second machine this host does not have. What
|
||||
> was verified is the same two checks against a local nxdns started from a
|
||||
> scratch data directory on an unprivileged port — `dig @127.0.0.1 -p 15353
|
||||
> example.com A +short` returned the A records, and `curl` against the web
|
||||
> port returned 200. Only the address and the port differ from the lines
|
||||
> above.
|
||||
To make every device use nxdns, set the DNS server your router hands out (its DHCP settings) to the nxdns machine's address. Leave the nxdns machine itself on another resolver: nxdns looks up its upstreams' names through it, and that should not depend on nxdns already running.
|
||||
|
||||
## Run in file mode
|
||||
|
||||
In file mode `/etc/nxdns/config.zon` is the configuration: every start converges the database onto it, and the admin interface refuses configuration edits with a 403 naming the file. Use it when you want the file in git and deployed by Ansible. Stay in database mode when you want the UI to be the way things change.
|
||||
In file mode `/etc/nxdns/config.zon` is the configuration. Every start applies the file, and the web interface refuses configuration changes and names the file instead. Use it when the file lives in git and a tool deploys it. [The configuration model](../explanation/configuration-model.md) compares the two modes.
|
||||
|
||||
The packaged unit is flagless on purpose — it is correct as shipped, and a commented-out alternative `ExecStart` in a unit file is documentation masquerading as configuration. File mode is a drop-in.
|
||||
### Switch to file mode
|
||||
|
||||
### Adopt file mode on a box that is already running
|
||||
|
||||
Run these in order. **Stop first**, and do not skip that: any edit made through the UI between an export and the restart would be silently reverted by the first reconcile, and `nxdns check` against a live database refuses to grade it (below).
|
||||
|
||||
If you are arriving here from an upgrade, the binary must already be the new one before you export. An export written by 0.0.1 carries a `.password = ""` line this binary refuses; see [the order trap](upgrade.md#the-order-trap-export-with-the-new-binary-not-the-old-one).
|
||||
Stop the service first, so no change made in the web interface is lost, then write the current configuration out as the file:
|
||||
|
||||
```sh
|
||||
systemctl stop nxdns
|
||||
nxdns export --out /etc/nxdns/config.zon
|
||||
chown root:nxdns /etc/nxdns/config.zon
|
||||
chmod 0640 /etc/nxdns/config.zon
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
```
|
||||
wrote /etc/nxdns/config.zon
|
||||
checking configuration file /etc/nxdns/config.zon
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
OK: no problems found
|
||||
```
|
||||
|
||||
Then add the drop-in and start:
|
||||
Add a drop-in that passes the file, and start:
|
||||
|
||||
```sh
|
||||
mkdir -p /etc/systemd/system/nxdns.service.d
|
||||
@@ -270,23 +153,18 @@ systemctl daemon-reload
|
||||
systemctl start nxdns
|
||||
```
|
||||
|
||||
The empty `ExecStart=` is required. Without it systemd appends a second command to the list rather than replacing the first, and the unit tries to run nxdns twice.
|
||||
|
||||
The first start after adoption changes nothing, because the file was rendered from the database it is now governing:
|
||||
The empty `ExecStart=` line is required: it clears the unit's own command instead of adding a second one. The first start changes nothing, because the file was written from the database it now governs:
|
||||
|
||||
```
|
||||
reconciled '/etc/nxdns/config.zon': no changes
|
||||
info(nxdns): authority: file (/etc/nxdns/config.zon)
|
||||
info(nxdns): nxdns <version> serving on udp [::]:53 tcp [::]:53 tcp 0.0.0.0:53; 1 upstream(s); blocklist generation 1
|
||||
```
|
||||
|
||||
`authority: file` is the line that confirms the drop-in took. Blocklists, compiled snapshots and client history all survive, and every later start on an unchanged file writes nothing either.
|
||||
Blocklists, their downloads and the query history all carry over.
|
||||
|
||||
The file now carries `web.password_hash`, so restrict it the same way step 4 does — `chown root:nxdns`, `chmod 0640`. The unit's `ReadOnlyPaths=/etc/nxdns` denies the service write access to that directory, so the process that reads the file cannot modify it.
|
||||
### Change the configuration
|
||||
|
||||
### Change the configuration from now on
|
||||
|
||||
Edit the file, validate it, restart:
|
||||
Edit the file, check it, restart:
|
||||
|
||||
```sh
|
||||
$EDITOR /etc/nxdns/config.zon
|
||||
@@ -294,18 +172,18 @@ nxdns check --config /etc/nxdns/config.zon
|
||||
systemctl restart nxdns
|
||||
```
|
||||
|
||||
Make `nxdns check --config` the precondition of any Ansible handler that restarts nxdns. A file-mode start reads the file on **every** boot, so a bad push that skips its handler does not fail at deploy time — it detonates at the next power cut. Validating before restarting turns that into a failed deploy at noon.
|
||||
|
||||
The restart prints what it changed:
|
||||
The restart logs what it changed:
|
||||
|
||||
```
|
||||
reconciled '/etc/nxdns/config.zon': upstreams +1 ~0 -0; settings +0 ~2 -0;
|
||||
settings keys changed: dns.port web.port
|
||||
```
|
||||
|
||||
### Leave file mode
|
||||
Because the file is read at every start, a broken file stops the service at its next restart, whenever that is. If a tool deploys the file, run `nxdns check --config` before it restarts nxdns, so a mistake fails the deploy instead.
|
||||
|
||||
Remove the drop-in and restart. The database already holds the last reconciled state, so nothing else is needed and the server comes back serving the same configuration:
|
||||
### Go back to database mode
|
||||
|
||||
Remove the drop-in and restart. The database already holds the last configuration the file set:
|
||||
|
||||
```sh
|
||||
rm /etc/systemd/system/nxdns.service.d/file-mode.conf
|
||||
@@ -316,98 +194,3 @@ systemctl restart nxdns
|
||||
```
|
||||
info(nxdns): authority: database
|
||||
```
|
||||
|
||||
> Verified on this host end to end, against a scratch `--data-dir` and a scratch
|
||||
> configuration path instead of `/var/lib/nxdns` and `/etc/nxdns`, on
|
||||
> unprivileged ports — this machine has neither of those directories, no root,
|
||||
> and no installed unit. Every `nxdns` line above was run and produced the output
|
||||
> shown, with only those paths and the port numbers in the `serving on` line
|
||||
> differing.
|
||||
>
|
||||
> The run: a database-mode instance was started, a blocklist source was added
|
||||
> through the API to make it UI-configured, then `nxdns check` against the live
|
||||
> database printed the uncheckpointed-log FAIL and exited 2 (which is why this
|
||||
> section stops the service first). After the stop, `nxdns export --out` wrote
|
||||
> the file, `nxdns check --config` on it exited 0 with `OK: no problems found`,
|
||||
> and the first file-mode start printed `reconciled '<path>': no changes` and
|
||||
> `authority: file (<path>)`. A second file-mode start printed `no changes`
|
||||
> again and loaded the 3096006-byte compiled blocklist from disk with no
|
||||
> download. Dropping the flag printed `authority: database` and served the same
|
||||
> configuration.
|
||||
>
|
||||
> The `systemctl`, `mkdir`, `cat > …/file-mode.conf` and `rm` lines need root and
|
||||
> an installed unit and were **not** run. What was checked instead:
|
||||
> `systemd-analyze verify` on `deploy/systemd/nxdns.service` with those exact two
|
||||
> `ExecStart` lines appended, which reported only the usual
|
||||
> `Command /usr/local/bin/nxdns is not executable` for the absent binary and
|
||||
> nothing about the override.
|
||||
|
||||
## Raspberry Pi 5
|
||||
|
||||
The Pi 5 is aarch64. Nothing about the procedure changes except which tarball you take:
|
||||
|
||||
```sh
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/nxdns-$VERSION-aarch64-linux-musl.tar.gz"
|
||||
sha256sum -c --ignore-missing SHA256SUMS.txt
|
||||
tar -xzf "nxdns-$VERSION-aarch64-linux-musl.tar.gz"
|
||||
cd "nxdns-$VERSION-aarch64-linux-musl"
|
||||
scp nxdns nxdns.service nxdns.conf pi:/tmp/
|
||||
```
|
||||
|
||||
Then follow steps 3 to 6 on the Pi.
|
||||
|
||||
> Partly verified on 2026-10-02: the `v0.0.21` aarch64 tarball downloaded and `sha256sum -c` printed `OK` for it. The `scp` and steps 3 to 6 were not run: `pi` is a placeholder for your Pi's hostname, and this page was written on an x86_64 machine with no Pi attached.
|
||||
|
||||
## Build from source instead
|
||||
|
||||
You do not need this to install nxdns, and it gets you a binary nobody has signed. It is here for two cases: you want to run something other than a tagged release, or you want to build the release yourself and compare it against the published one. For the second case, follow [Verify a release](verify-a-release.md) rather than this section — it says what the comparison is and is not worth.
|
||||
|
||||
Requires Zig 0.16.0 and Node.js. From the repository root:
|
||||
|
||||
```sh
|
||||
(cd admin && npm ci && npm run build)
|
||||
VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
|
||||
zig build dist -Dversion-string="$VERSION" \
|
||||
-Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
|
||||
```
|
||||
|
||||
The first command builds the admin interface into `admin/dist`; the last one embeds that directory in the binary. Build the interface every time, before the binary: a stale `admin/dist` ships an admin UI that does not match the API it talks to. `dist` refuses to run against the `admin/dist-placeholder` default for exactly that reason, so there is no way to skip it by accident.
|
||||
|
||||
`-Dversion-string` is required and has no default. It is what `nxdns version` prints. Take it from `build.zig.zon` rather than inventing one: `verify-dist` asserts that the version under build equals `.version` there, so a made-up string like `0.0.0-local` builds but then fails verification.
|
||||
|
||||
What comes out under `zig-out/dist/` is the same set a release publishes, minus the signature and the image digest:
|
||||
|
||||
- `bin/<triple>/nxdns` — the stripped static binary, one per target
|
||||
- `stage/nxdns-<version>-<triple>/` — the staged payload, one per target
|
||||
- `nxdns-<version>-<triple>.tar.gz` — one tarball per target
|
||||
- `SHA256SUMS` — the two tarball hashes. The release publishes this as `SHA256SUMS.txt`, with a third line for the image digest appended
|
||||
|
||||
The two targets are `x86_64-linux-musl` and `aarch64-linux-musl`. Both binaries are statically linked and need nothing installed on the target host.
|
||||
|
||||
Check the result the same way the release pipeline does:
|
||||
|
||||
```sh
|
||||
zig build verify-dist -Dversion-string="$VERSION" \
|
||||
-Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
|
||||
```
|
||||
|
||||
`verify-dist` extracts each archive and asserts the ELF is static and within the size budget, that the layout and file modes are exactly what step 1 lists, and that `nxdns version` prints what was built. It exits non-zero on any failure.
|
||||
|
||||
> Verified on this host: `zig build dist` and `zig build verify-dist` were both
|
||||
> run to completion with the version taken from `build.zig.zon`. `dist`
|
||||
> produced the two tarballs, `SHA256SUMS` and the staged payloads described
|
||||
> above; `verify-dist` exited 0 with every check passing and the aarch64
|
||||
> `nxdns version` check skipped for want of `-fqemu`. Passing a made-up
|
||||
> `-Dversion-string=0.0.0-local` was also run: `dist` succeeded and
|
||||
> `verify-dist` then failed with
|
||||
> `FAIL zon-version: build.zig.zon says '0.0.1', the build says '0.0.0-local'`,
|
||||
> which is why this section reads the version out of `build.zig.zon`.
|
||||
|
||||
From here, join the page at step 2 with the staged directory in place of the extracted one:
|
||||
|
||||
```sh
|
||||
cd "zig-out/dist/stage/nxdns-$VERSION-x86_64-linux-musl"
|
||||
scp nxdns nxdns.service nxdns.conf target:/tmp/
|
||||
```
|
||||
|
||||
The aarch64 binary is built by the same command and needs no toolchain on the Pi.
|
||||
|
||||
@@ -1,139 +0,0 @@
|
||||
# Measure performance
|
||||
|
||||
`tools/bench.zig` measures the three things nxdns can measure in-process: blocklist lookup latency, cache-hit latency, and blocklist compile throughput. Sustained query rate is not one of them — that one is end-to-end and needs a load generator pointed at a running server.
|
||||
|
||||
The numbers this project treats as targets, and the numbers measured so far, are in the [performance reference](../reference/performance.md). Why those targets exist and why CI does not gate on them is in [performance and testing](../explanation/performance-and-testing.md).
|
||||
|
||||
## Run the whole bench
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast
|
||||
```
|
||||
|
||||
That runs all three suites with the defaults: 1,000,000 domains, 200,000 iterations per suite, seed `0x5eed`. It takes minutes, most of it generating and loading the million-domain list.
|
||||
|
||||
`-Doptimize=ReleaseFast` is not optional if you want the numbers to mean anything. A Debug build says so before it prints:
|
||||
|
||||
```
|
||||
warning: Debug build; run with -Doptimize=ReleaseFast for meaningful numbers
|
||||
```
|
||||
|
||||
## Run one suite, smaller
|
||||
|
||||
Everything after `--` goes to the harness. A suite name selects one of `filter`, `cache`, `compile` (the default is `all`), and `--domains` / `--iters` shrink the load:
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast -- filter --domains=100000 --iters=20000
|
||||
```
|
||||
|
||||
```
|
||||
nxdns bench suite=filter domains=100000 iters=20000 seed=0x5eed optimize=ReleaseFast
|
||||
|
||||
suite ops p50(us) p95(us) p99(us) max(us)
|
||||
filter 20000 2.38 2.76 2.88 20.32
|
||||
blocked 6670/20000, 32 regex rules, Snapshot.memoryBytes 3.0 MiB, VmRSS 5.6 MiB
|
||||
target p95 < 1ms: PASS
|
||||
target VmRSS < 100 MiB: PASS
|
||||
```
|
||||
|
||||
A reduced run is good for checking the harness works and for a rough regression signal. It is not a result: the memory figure scales with `--domains`, so 100,000 domains says nothing about the 1,000,000-domain memory target.
|
||||
|
||||
The other two suites:
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast -- cache --iters=20000
|
||||
```
|
||||
|
||||
```
|
||||
suite ops p50(us) p95(us) p99(us) max(us)
|
||||
cache 20000 0.14 0.18 0.20 5.14
|
||||
hits 10000/20000, DnsCache.memoryBytes 4.3 MiB, VmRSS 6.3 MiB
|
||||
target p95 < 5ms: PASS
|
||||
```
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast -- compile --domains=100000
|
||||
```
|
||||
|
||||
```
|
||||
suite ops p50(us) p95(us) p99(us) max(us)
|
||||
compile 100000 wall 15.623ms, 6400464 lines/s, 100000 domains kept (informational)
|
||||
```
|
||||
|
||||
`--seed=N` changes the generated domains and the query order; the default is `0x5eed`, so two runs on the same machine are comparable. `--domains` caps at 4,000,000, and the `compile` suite additionally refuses more than 2,000,000 — the compiler's own limit.
|
||||
|
||||
An argument the harness does not recognise stops it before any measuring:
|
||||
|
||||
```
|
||||
error: unknown argument 'nosuch'
|
||||
usage: zig build bench -Doptimize=ReleaseFast -- [filter|cache|compile|all] [--domains=N] [--iters=N] [--seed=N] [--assert]
|
||||
```
|
||||
|
||||
## Read the output
|
||||
|
||||
- `p50`/`p95`/`p99`/`max` are per-operation microseconds, nearest-rank over every iteration. What one operation means differs per suite: for `filter` it is normalising a name plus evaluating it against the snapshot; for `cache` it is building the key, getting the entry and stamping the response id.
|
||||
- `blocked N/M` and `hits N/M` are sanity counters. The harness aborts if either is zero — a suite that never hits its own path measures nothing.
|
||||
- `32 regex rules` on the `filter` line is the rule set the suite loads. No generated query matches any of them, so every operation runs all 32 programs to their end, which is the costly case and the one worth measuring.
|
||||
- Two memory figures appear on purpose. `Snapshot.memoryBytes` and `DnsCache.memoryBytes` are the in-repo accounting of those structures; `VmRSS` is what the kernel holds resident for the whole process, allocator slack and code included. The truth is between them, and the memory target is judged on `VmRSS`.
|
||||
- `target ...: PASS` / `FAIL` lines appear for the targets a suite covers. On a plain run they are informational and the exit code stays 0.
|
||||
|
||||
## Fail the run when a target is missed
|
||||
|
||||
`--assert` turns those lines into an exit code — 1 when any target was exceeded, 0 otherwise. This is meant for an acceptance run on hardware you control, not for CI:
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast -- --assert
|
||||
```
|
||||
|
||||
The full-scale form is the one worth asserting on, because the memory target only means something at a million domains. On this development host the reduced form was used to check the flag itself:
|
||||
|
||||
```sh
|
||||
zig build bench -Doptimize=ReleaseFast -- filter --domains=100000 --iters=20000 --assert
|
||||
```
|
||||
|
||||
```
|
||||
filter 20000 2.34 2.71 2.85 15.06
|
||||
blocked 6670/20000, 32 regex rules, Snapshot.memoryBytes 3.0 MiB, VmRSS 5.6 MiB
|
||||
target p95 < 1ms: PASS
|
||||
target VmRSS < 100 MiB: PASS
|
||||
```
|
||||
|
||||
**Not verified on this host at full scale:** the plain `zig build bench -Doptimize=ReleaseFast -- --assert` above was not run during the writing of this page — the default run takes minutes. The reduced runs shown were all executed as written. The full-scale numbers already recorded for this host are in the [performance reference](../reference/performance.md).
|
||||
|
||||
## Measure sustained query rate
|
||||
|
||||
The bench harness cannot do this. Query rate is a property of the whole server — sockets, upstreams, the query log writer — so it has to be driven from outside, against the real binary, on the machine you care about.
|
||||
|
||||
Start nxdns with real blocklists configured, then drive it from another host on the LAN with a DNS load generator such as `dnsperf`:
|
||||
|
||||
```sh
|
||||
dnsperf -s 192.168.1.10 -p 53 -d queries.txt -c 20 -Q 200 -l 60
|
||||
```
|
||||
|
||||
Read the client's own rate and the server's `/metrics` together: a load generator that reports 200 qps while the server counts fewer has lost queries somewhere, and that is the interesting number.
|
||||
|
||||
**Not verified on this host:** `dnsperf` is not installed here and the target platform is a Raspberry Pi 5, not this development machine. The command above is the shape of the measurement, not a transcript.
|
||||
|
||||
## Measure memory on a running server
|
||||
|
||||
The bench measures one structure at a time. A running server's memory also depends on the most concurrent work it has seen since it started, so read it on the server itself, after it has served a normal day:
|
||||
|
||||
```sh
|
||||
pid=$(pidof nxdns)
|
||||
grep -E 'VmRSS|VmHWM|Threads' /proc/$pid/status
|
||||
curl -s http://127.0.0.1:8080/metrics | grep '^nxdns_.*_peak'
|
||||
```
|
||||
|
||||
- `VmRSS` is what the process holds resident now. `VmHWM` is the most it has ever held, which is normally the last blocklist refresh.
|
||||
- `Threads` is a high-water too: the I/O runtime adds a worker thread only when every existing worker is busy, and never retires one. The count is the largest the worker pool has been since start, plus the main thread.
|
||||
- `nxdns_dns_in_flight_peak` is the most queries handled at once, every listener together.
|
||||
- `nxdns_tcp_server_connections_peak`, `nxdns_dot_server_connections_peak` and `nxdns_doh_server_connections_peak` are the most connections one listener has held at once. TCP/53 has one listener per address family; the gauge is the larger of the two.
|
||||
- `nxdns_querylog_queue_peak` is the most entries that have waited for the query log writer at once. It can overstate the true peak by the entries in transit at that instant, never understate it.
|
||||
|
||||
Each worker thread's stack is its own anonymous mapping in `/proc/$pid/smaps`, directly above a one-page `---p` guard, and every worker's mapping has the same size. Its `Rss` is the stack that thread has actually touched.
|
||||
|
||||
**Verified on this host** against a static x86_64 musl build under a burst of 300 UDP queries: the gauges and the stack mappings behave as described. Not yet run on the Pi.
|
||||
|
||||
## Where to run it
|
||||
|
||||
The target platform is a Raspberry Pi 5. Numbers from a development x86_64 box do not transfer — the Pi's Cortex-A76 is far slower — so a passing run here is evidence the harness works and a baseline for spotting regressions on the machine development happens on, and nothing more. Run `--assert` on the Pi, where the numbers mean something.
|
||||
@@ -1,275 +1,112 @@
|
||||
# Set up admin authentication
|
||||
|
||||
The admin interface and its API are protected by a single operator password. With no password set, every route is open to anything that can reach the web port. Set one.
|
||||
The web interface is protected by a single password. With no password set, anyone who can reach the web port can change nxdns's configuration, so set one before you let other machines reach it.
|
||||
|
||||
The commands below run against the scratch lab from [enable DoH and DoT](enable-doh-and-dot.md): data directory `/tmp/nxdns-lab/data`, web listener on `127.0.0.1:8451`. On a real install the data directory is `/var/lib/nxdns` and the web port is 8080.
|
||||
## Set the password in the web interface
|
||||
|
||||
## 1. Set the password
|
||||
In database mode, open **System**, type the new password into **password** and **confirm password** under **Web**, and press **Save**. The interface logs you out at once, and every other session ends with it; log back in with the new password.
|
||||
|
||||
Put it in the configuration file, under `web`:
|
||||
To change the password later, do the same again.
|
||||
|
||||
## Set it in the configuration file
|
||||
|
||||
In file mode, or for a first configuration you import, put the password under `web`:
|
||||
|
||||
```zon
|
||||
.{
|
||||
.groups = .{.{ .name = "default" }},
|
||||
.upstreams = .{.{ .url = "https://cloudflare-dns.com/dns-query" }},
|
||||
.web = .{ .bind = "127.0.0.1", .port = 8451, .password = "lab-password" },
|
||||
}
|
||||
.web = .{ .password = "choose-a-real-password" },
|
||||
```
|
||||
|
||||
The plaintext is hashed with argon2id into `web.password_hash` and discarded. It becomes no database row and appears in no log line. Setting both `password` and `password_hash` in one file is refused:
|
||||
|
||||
```
|
||||
web.password: password and password_hash are both set; ambiguity in a security setting is refused
|
||||
import failed: PasswordAndHashBothSet
|
||||
```
|
||||
|
||||
Applying that file — with `nxdns import`, or with a `nxdns run --config` start — announces the change:
|
||||
nxdns stores only an argon2id hash of it, in `web.password_hash`, and never logs it. Applying the file, at the next start in file mode or with `nxdns import`, logs:
|
||||
|
||||
```
|
||||
web authentication is now enabled
|
||||
```
|
||||
|
||||
### Absent, empty, and set are three different things
|
||||
### Put a hash in the file instead
|
||||
|
||||
The two fields are optional, and the difference between leaving one out and setting it to `""` is the difference between keeping your password and removing it:
|
||||
A configuration file kept in git or in the Nix store should not hold a plaintext password. Set the password once, then copy the hash out of an export:
|
||||
|
||||
| The file says | Effect on the stored password |
|
||||
```sh
|
||||
nxdns export | grep password
|
||||
```
|
||||
|
||||
```
|
||||
.password = null,
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…",
|
||||
```
|
||||
|
||||
Put that `.password_hash` line in your file in place of `.password`. The hash installs the same password without revealing it. A file that sets both fields is refused:
|
||||
|
||||
```
|
||||
web.password: password and password_hash are both set; ambiguity in a security setting is refused
|
||||
```
|
||||
|
||||
### What the file's password fields do
|
||||
|
||||
| The file says | What happens to the stored password |
|
||||
| --- | --- |
|
||||
| Neither field | Nothing. It stays exactly as it was. |
|
||||
| `.password = "…"` | Installs that password. Unchanged plaintext keeps the existing hash rather than re-hashing it. |
|
||||
| Neither field | Nothing. It stays as it was. |
|
||||
| `.password = "…"` | Sets that password. |
|
||||
| `.password_hash = "$argon2id$…"` | Sets the password that hash belongs to. |
|
||||
| `.password_hash = ""` | Removes the password and turns authentication off. |
|
||||
| `.password = ""` | Refused. |
|
||||
| `.password_hash = "$argon2id$…"` | Installs that hash, for example from an export. |
|
||||
| `.password_hash = ""` | **Removes the password.** Authentication is off. |
|
||||
|
||||
Absence has to mean "keep", because the alternative is a foot-gun with a live round in it. An export carries the full PHC string, which is long and ugly, and sooner or later someone trims that line out of a file before committing it — meaning "leave the password alone". If absence meant "no password", that edit would open the admin interface to the whole LAN without a word.
|
||||
|
||||
So removing the password takes the explicit empty string:
|
||||
Leaving both fields out keeps the password, so deleting the hash line from a file before you commit it never opens the interface by accident. Turning authentication off takes the explicit empty hash, and logs:
|
||||
|
||||
```
|
||||
web authentication is now disabled
|
||||
```
|
||||
|
||||
And an empty plaintext is refused outright, because hashing the empty string would switch authentication *on* while making every login impossible — the login handler rejects empty passwords:
|
||||
## If you have lost the password
|
||||
|
||||
```
|
||||
FAIL web.password: password is set to the empty string; omit the field to keep the stored password, or set password_hash = "" to disable authentication
|
||||
```
|
||||
|
||||
Which of steps 4 and 5 applies to your server depends on its authority. Under `nxdns run --config FILE` the file is the password: edit it and restart, and the API refuses the change with a 403. Under bare `nxdns run` the database holds it, and step 4 or step 5 is how it moves.
|
||||
|
||||
## 2. Log in
|
||||
|
||||
Login is `POST /api/auth/login` with a JSON body. Without a session, the API answers 401:
|
||||
The web interface cannot help, so go through the database. Stop nxdns first: a running server keeps checking logins against the hash it read when it started.
|
||||
|
||||
```sh
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8451/api/overview
|
||||
systemctl stop nxdns
|
||||
nxdns export --out /root/nxdns-rekey.zon
|
||||
```
|
||||
|
||||
```
|
||||
401
|
||||
```
|
||||
|
||||
Log in and keep the cookie:
|
||||
|
||||
```sh
|
||||
curl -sS -c /tmp/nxdns-lab/cookies.txt \
|
||||
-X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"password":"lab-password"}'
|
||||
```
|
||||
|
||||
```json
|
||||
{"authenticated":true,"auth_required":true}
|
||||
```
|
||||
|
||||
The session token comes back in a `Set-Cookie` header, not in the body. In the jar it looks like this (value redacted here):
|
||||
|
||||
```
|
||||
#HttpOnly_127.0.0.1 FALSE / FALSE 1786559938 nxdns_session <redacted>
|
||||
```
|
||||
|
||||
The cookie is named `nxdns_session` and carries `HttpOnly; SameSite=Lax; Path=/`. Its `Max-Age` comes from `web.session_ttl_hours`. Send it back on every later call:
|
||||
|
||||
```sh
|
||||
curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w '%{http_code}\n' \
|
||||
http://127.0.0.1:8451/api/overview
|
||||
```
|
||||
|
||||
```
|
||||
200
|
||||
```
|
||||
|
||||
A wrong password and an unknown one are the same answer, so a guess learns nothing:
|
||||
|
||||
```sh
|
||||
curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"wrong"}' \
|
||||
-w ' (http %{http_code})\n'
|
||||
```
|
||||
|
||||
```
|
||||
{"error":"invalid password"} (http 401)
|
||||
```
|
||||
|
||||
The server logs the address and the outcome, never the password:
|
||||
|
||||
```
|
||||
info(web_auth): web login accepted for 127.0.0.1:34040
|
||||
warning(web_auth): web login refused for 127.0.0.1:59670
|
||||
```
|
||||
|
||||
Sessions live in memory only. A restart logs everyone out. Thirty-two concurrent sessions are kept; a thirty-third login evicts the least recently used one.
|
||||
|
||||
## 3. Log out
|
||||
|
||||
```sh
|
||||
curl -sS -b /tmp/nxdns-lab/cookies.txt -c /tmp/nxdns-lab/cookies.txt \
|
||||
-X POST http://127.0.0.1:8451/api/auth/logout
|
||||
curl -sS -b /tmp/nxdns-lab/cookies.txt -o /dev/null -w 'overview: %{http_code}\n' \
|
||||
http://127.0.0.1:8451/api/overview
|
||||
```
|
||||
|
||||
```
|
||||
{"authenticated":false}
|
||||
overview: 401
|
||||
```
|
||||
|
||||
Logging out with a stale cookie, or with none, answers the same way. The point of logging out is to end up logged out, and that is where such a request already is.
|
||||
|
||||
## 4. Change the password on a running server
|
||||
|
||||
This is a database-mode procedure. In file mode `PUT /api/settings` answers 403 naming the file; edit `web.password` there and restart instead.
|
||||
|
||||
Send the new one to `PUT /api/settings` as `web.password`. The response is the full settings document; `password` is write-only and `password_hash` is neither readable nor directly writable, so neither value comes back.
|
||||
|
||||
```sh
|
||||
curl -sS -c /tmp/nxdns-lab/c2.txt -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"lab-password"}'
|
||||
curl -sS -b /tmp/nxdns-lab/c2.txt -X PUT http://127.0.0.1:8451/api/settings \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"web":{"password":"a-new-password"}}'
|
||||
```
|
||||
|
||||
Changing the password ends every session, including the one that made the change:
|
||||
|
||||
```sh
|
||||
curl -sS -b /tmp/nxdns-lab/c2.txt -o /dev/null -w 'old session: %{http_code}\n' \
|
||||
http://127.0.0.1:8451/api/overview
|
||||
curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"lab-password"}' \
|
||||
-w ' (old password)\n'
|
||||
curl -sS -c /tmp/nxdns-lab/c3.txt -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"a-new-password"}' \
|
||||
-w ' (new password)\n'
|
||||
```
|
||||
|
||||
```
|
||||
old session: 401
|
||||
{"error":"invalid password"} (old password)
|
||||
{"authenticated":true,"auth_required":true} (new password)
|
||||
```
|
||||
|
||||
Log back in with the new password. That is the whole rotation.
|
||||
|
||||
## 5. Change the password without the API
|
||||
|
||||
If you have lost the password, the admin interface cannot help — go through the database instead. Export, edit, import. `nxdns export` always writes `.password = null` and carries the hash, so an exported file re-imports without anyone knowing the password. To install a new one, put it in `.password` and clear `.password_hash`:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data --out /tmp/nxdns-lab/rekeyed.zon
|
||||
```
|
||||
|
||||
Edit the `web` section of `/tmp/nxdns-lab/rekeyed.zon`: set `.password` to the new value and **delete the `.password_hash` line entirely**, so the `web` block carries one password field and not two:
|
||||
In the `web` section of `/root/nxdns-rekey.zon`, set `.password` to the new password and delete the `.password_hash` line, so only one password field is left:
|
||||
|
||||
```zon
|
||||
.password = "offline-password",
|
||||
.password = "a-new-password",
|
||||
```
|
||||
|
||||
Deleting the line is the part to get right. Setting `.password_hash = ""` alongside a plaintext password does not clear the way for it — an empty string is a present value meaning "no password", so the file then states two contradictory things and is refused:
|
||||
|
||||
```
|
||||
FAIL web.password: password and password_hash are both set; ambiguity in a security setting is refused
|
||||
import failed: PasswordAndHashBothSet
|
||||
```
|
||||
|
||||
Stop the server before importing. `import` rewrites the stored hash underneath a process that read it at startup; a running server keeps verifying against the old one, so skipping the stop leaves the new password not working until the next restart. In the lab the server is a foreground `nxdns run`, so Ctrl-C in its terminal stops it, and it goes back up with the same command:
|
||||
Then load it and start again:
|
||||
|
||||
```sh
|
||||
# Ctrl-C the `nxdns run` terminal, or `kill` its pid from another shell
|
||||
nxdns import /tmp/nxdns-lab/rekeyed.zon --data-dir /tmp/nxdns-lab/data
|
||||
nxdns run --data-dir /tmp/nxdns-lab/data
|
||||
nxdns import /root/nxdns-rekey.zon
|
||||
systemctl start nxdns
|
||||
rm /root/nxdns-rekey.zon
|
||||
```
|
||||
|
||||
```
|
||||
imported /tmp/nxdns-lab/rekeyed.zon
|
||||
imported /root/nxdns-rekey.zon
|
||||
```
|
||||
|
||||
No flag is needed: replacing a password edits a settings value and deletes no rows.
|
||||
In file mode, change the password in your configuration file and restart instead.
|
||||
|
||||
On a real install the stop and start are `systemctl stop nxdns` and `systemctl start nxdns` around the same `import` — **not verified on this host**, which has no installed nxdns systemd unit (`systemctl status nxdns` answers `Unit nxdns.service could not be found.`) and where `systemctl` needs root. See [back up and restore](back-up-and-restore.md).
|
||||
## Sessions
|
||||
|
||||
Once it is back up the old password is refused and the new one works:
|
||||
A login lasts `web.session_ttl_hours`, 24 hours by default. Sessions are kept in memory, so restarting nxdns logs everyone out. Up to 32 sessions are open at once; a 33rd login ends the one used least recently.
|
||||
|
||||
```sh
|
||||
curl -sS -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"lab-password"}' \
|
||||
-w ' (old password, http %{http_code})\n'
|
||||
curl -sS -c /tmp/nxdns-lab/c5.txt -X POST http://127.0.0.1:8451/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"offline-password"}' \
|
||||
-w ' (new password, http %{http_code})\n'
|
||||
curl -sS -b /tmp/nxdns-lab/c5.txt -o /dev/null -w 'overview: %{http_code}\n' \
|
||||
http://127.0.0.1:8451/api/overview
|
||||
```
|
||||
Each login is logged with the address it came from, never with the password:
|
||||
|
||||
```
|
||||
{"error":"invalid password"} (old password, http 401)
|
||||
{"authenticated":true,"auth_required":true} (new password, http 200)
|
||||
overview: 200
|
||||
info(web_auth): web login accepted for 192.168.1.20:34040
|
||||
warning(web_auth): web login refused for 192.168.1.20:59670
|
||||
```
|
||||
|
||||
The next export shows the new hash and a null `password` again:
|
||||
Logins count against `web.api_rate_limit_per_min`, which limits how fast anyone can guess. Requests from the nxdns machine itself are exempt by default (`web.api_localhost_exempt`).
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /tmp/nxdns-lab/data | grep password
|
||||
## Behind a reverse proxy
|
||||
|
||||
A reverse proxy on the same machine connects from `127.0.0.1`, so every request it forwards would be exempt from the rate limit. List the proxy in `web.trusted_proxies`, and nxdns reads each client's real address from the `X-Forwarded-For` header the proxy adds:
|
||||
|
||||
```zon
|
||||
.web = .{ .trusted_proxies = "127.0.0.1" },
|
||||
```
|
||||
|
||||
```
|
||||
.password = null,
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$xqzK66LgiWGvyCmCl6ZRa3GHH0nS5qZnRgVfWmeGadc$1mafhflKFIg3vcHjJaDMAXGQiOjtym2UADZsPW1xkfw",
|
||||
```
|
||||
The proxy must add its own entry to that header rather than pass on whatever the client sent. If it cannot, turn `web.api_localhost_exempt` off instead.
|
||||
|
||||
See [back up and restore](back-up-and-restore.md) for when `import` does need `--allow-delete`.
|
||||
|
||||
## What happens with no password set
|
||||
|
||||
Authentication is off. Every route is open, and a login attempt succeeds without minting anything — there is nothing to log in to, and a session that authorises nothing would be a lie for the browser to store:
|
||||
|
||||
```sh
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8453/api/overview
|
||||
curl -sS -X POST http://127.0.0.1:8453/api/auth/login \
|
||||
-H 'content-type: application/json' -d '{"password":"anything"}'
|
||||
```
|
||||
|
||||
```
|
||||
200
|
||||
{"authenticated":true,"auth_required":false}
|
||||
```
|
||||
|
||||
`auth_required: false` is how the admin interface knows to stop showing a login form. Treat this as a lab-only state: bind the web listener to a trusted interface at the very least, and preferably set a password.
|
||||
|
||||
## Notes
|
||||
|
||||
- A stored hash this build cannot parse is a 500, not a 401. Answering 401 would tell an operator with a corrupted `web.password_hash` that their password is wrong, and they would retype a password that can never verify.
|
||||
- Requests from the box itself skip the API rate limit by default (`web.api_localhost_exempt`).
|
||||
- **If you put a reverse proxy in front of the admin interface, configure `web.trusted_proxies` or turn `web.api_localhost_exempt` off.** A proxy on the same box connects from loopback, so every request arrives exempt and the API limiter — the only brake on guessing the admin password — stops applying to anyone. Listing the proxy's address in `web.trusted_proxies` makes nxdns read the client's address from the `X-Forwarded-For` the proxy appends, so the limiter and the SSE connection cap bind each real client again:
|
||||
|
||||
```zig
|
||||
.web = .{
|
||||
.trusted_proxies = "127.0.0.1",
|
||||
},
|
||||
```
|
||||
|
||||
The proxy must append its own entry to that header. A proxy that forwards a client-supplied `X-Forwarded-For` unchanged is not one to trust.
|
||||
- `web.session_ttl_hours`, `web.api_rate_limit_per_min` and the rest are in the [configuration reference](../reference/configuration.md); the routes are in the [API reference](../reference/api.md).
|
||||
|
||||
Every command on this page was executed on this host as written, against the lab described at the top, except the `systemctl` stop and start named in step 5 and marked **not verified on this host** there. That includes the whole of steps 2 to 5, re-run for this revision: the login, logout and rate-limit transcripts reproduced exactly as printed, the both-set refusal in step 5 was reproduced by leaving `.password_hash = ""` in the file, and the rekey then succeeded once that line was deleted. The cookie jar's expiry timestamp is the one that run produced and will differ on yours.
|
||||
The [configuration reference](../reference/configuration.md#web) lists every `web` setting.
|
||||
|
||||
@@ -1,397 +0,0 @@
|
||||
# Troubleshoot nxdns
|
||||
|
||||
Symptoms an nxdns install actually produces, what to run to identify each one, and what to change. Every symptom on this page was reproduced on the machine that wrote it, and every diagnosis command was run there. Two details differ from a real install and cannot be otherwise on that machine: it has no installed service, so the log lines were read from a foreground run instead of `journalctl -u nxdns`, and ports 53 and 8080 were occupied, so DNS and the API were exercised on unprivileged ports. Fixes that need root are marked.
|
||||
|
||||
The exit codes themselves are listed in [the CLI reference](../reference/cli.md).
|
||||
|
||||
## The service exits with code 2
|
||||
|
||||
**Symptom.** The process stops immediately. The last two lines are the error and a pointer:
|
||||
|
||||
```
|
||||
nxdns run failed: NoUsableUpstreams
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
Exit 2 means the configuration is wrong and you can fix it. Every subcommand uses the same definition, so a file `run` exits 2 on exits 2 from `check` and `import` too.
|
||||
|
||||
**Diagnosis.**
|
||||
|
||||
```sh
|
||||
nxdns check
|
||||
```
|
||||
|
||||
`check` prints every problem it finds, not the first, and names the source it checked on its first line.
|
||||
|
||||
**Fixes by cause.**
|
||||
|
||||
- `NoUsableUpstreams` — the database has no enabled upstream. On a fresh install in database mode this is simply an empty database, and the run says what to do about it on the next line:
|
||||
|
||||
```
|
||||
nxdns run failed: NoUsableUpstreams
|
||||
run `nxdns check` to see the configuration in full
|
||||
load one with `nxdns import <file>`, or make a file the source of truth with `nxdns run --config <file>`
|
||||
```
|
||||
|
||||
Write a configuration file and take either exit: `nxdns import <file>` to load it into the database once, or add `--config <file>` to `ExecStart` to make the file the configuration from then on.
|
||||
- `ManagedConfigUnreadable` — the service runs `run --config FILE` and that file is missing or the process may not read it. The path is in the FAIL line above the failure. File mode never falls back to the database, on purpose: a fallback would turn a bad deploy into a silently stale configuration.
|
||||
- `BadCertificate` — a DoH or DoT listener is enabled and its certificate or key is unreadable, too large, unparseable, or the key does not belong to the certificate. `run` names both paths before it exits: `doh_server: '<cert>' + '<key>': certificate file is not readable`.
|
||||
|
||||
`check` catches this without starting a listener. It loads both PEM files and tests the key against the certificate through the same code `run` uses, so it fails on exactly what `run` would fail on. Reproduced here with a self-signed pair and the key from a second, unrelated pair:
|
||||
|
||||
```
|
||||
$ nxdns check --config config.zon
|
||||
warning(tls_server): mbedtls_pk_check_pair failed: RSA - Key failed to pass the validity check of the library (-16896)
|
||||
checking configuration file config.zon
|
||||
FAIL doh_server.key_path: 'mismatched-key.pem': private key does not belong to the certificate
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
# exit 2
|
||||
|
||||
$ nxdns run --config config.zon --data-dir ./data
|
||||
warning(tls_server): mbedtls_pk_check_pair failed: RSA - Key failed to pass the validity check of the library (-16896)
|
||||
doh_server: 'cert.pem' + 'mismatched-key.pem': private key does not belong to the certificate
|
||||
nxdns run failed: BadCertificate # exit 2
|
||||
```
|
||||
|
||||
The `warning(tls_server)` line comes from mbedTLS on stderr and can appear before the `checking` line, which is on stdout. A cert file containing `not a certificate` fails the same way, with `FAIL doh_server.cert_path: 'junk.pem': certificate PEM could not be parsed`. An unreadable file reads `FAIL doh_server.cert_path: '<path>': certificate file is not readable`.
|
||||
|
||||
Fix the path, the ownership, or the pair; see [Enable DoH and DoT](enable-doh-and-dot.md).
|
||||
- `BadRateLimit` — a rate limit or window is zero. `import` refuses such a configuration, so this only reaches a database that was edited by hand.
|
||||
- `BadBindAddress` — `dns.bind_ipv4` or `dns.bind_ipv6` is not an address of that family.
|
||||
|
||||
## A configuration file you just wrote is rejected
|
||||
|
||||
**Symptom.** `nxdns run --config`, `nxdns check --config` or `nxdns import` prints the validation problem and stops with exit 2:
|
||||
|
||||
```
|
||||
FAIL groups: no group named 'default'; every unknown client is assigned to it
|
||||
nxdns run failed: MissingDefaultGroup
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
A syntax error behaves the same way:
|
||||
|
||||
```
|
||||
FAIL config: 3:16: error: expected ',' after initializer
|
||||
nxdns run failed: ParseZon
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
So does a file whose upstream list is empty or all disabled:
|
||||
|
||||
```
|
||||
FAIL upstreams: at least one upstream must be enabled
|
||||
nxdns run failed: NoUpstreams
|
||||
run `nxdns check` to see the configuration in full
|
||||
```
|
||||
|
||||
`NoUpstreams` from a file is not the same fault as `NoUsableUpstreams` above: the first is a file `run` refused, the second is a database `run` accepted and found empty. Both are exit 2.
|
||||
|
||||
**Diagnosis.** Run the same file through `check`, which reports the same problems and exits 2:
|
||||
|
||||
```sh
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
**Fix.** Correct the file the diagnostics name and start again. Nothing was applied — a file-mode reconcile happens in one transaction that rolls back, and a failed `import` leaves the database untouched. The exit code does not depend on which command read the file: all three of these files were run through `run`, `check` and `import` here, and every one of the nine combinations exited 2 with the same diagnostic.
|
||||
|
||||
Under the shipped systemd unit an exit 2 stops the service rather than restarting it (`RestartPreventExitStatus=2 64`), so the journal holds the diagnostics instead of drowning them in a restart loop. `systemctl start nxdns` once the file is fixed.
|
||||
|
||||
Make `nxdns check --config <file>` the precondition in whatever pushes the file. In file mode every boot reads it, so an unvalidated bad push does not fail at deploy time — it fails at the next restart, which may be a power cut at 3am.
|
||||
|
||||
## `nxdns check` fails on a server that is running fine
|
||||
|
||||
**Symptom.** The service is up and answering, but `nxdns check` on the same machine exits 2 with one long line about a write-ahead log:
|
||||
|
||||
```
|
||||
checking database /var/lib/nxdns/config.db
|
||||
FAIL /var/lib/nxdns/config.db: uncheckpointed changes are waiting in /var/lib/nxdns/config.db-wal, and reading without writing would answer from the older settings in the main file; `nxdns run` applies them. A running nxdns normally holds this log, which is the usual reason to see this line.
|
||||
```
|
||||
|
||||
Nothing is damaged. `check` opens `config.db` immutable so that it can never write to it, and an immutable open ignores the write-ahead log. When that log holds bytes, the newest settings are in it and the main file holds older ones, so `check` refuses rather than grade stale values.
|
||||
|
||||
The log holds bytes after a configuration write that has not been checkpointed yet, which on a running server means someone changed something through the web interface or the API. A server that has only been answering queries has an empty `config.db-wal` and `check` reads it normally — so this line comes and goes, and its absence is not proof that nothing is running.
|
||||
|
||||
**Fix.** Check the exported configuration instead of the live file:
|
||||
|
||||
```sh
|
||||
nxdns export --data-dir /var/lib/nxdns --out /tmp/current.zon
|
||||
nxdns check --config /tmp/current.zon
|
||||
```
|
||||
|
||||
`export` opens the database read/write and does see the log, so it renders the settings that are actually in force. Stopping the service and checking again works too: a clean shutdown checkpoints the log away.
|
||||
|
||||
> Reproduced here on a scratch data directory rather than `/var/lib/nxdns` —
|
||||
> that path is the only substitution in the output above. nxdns was started on
|
||||
> unprivileged ports; `config.db-wal` was 0 bytes and `check` exited 0; one
|
||||
> `POST /api/blocklists` took it to 8272 bytes and `check` then printed the line
|
||||
> above and exited 2; `export` from the same live directory succeeded and its
|
||||
> output checked clean; and after a clean shutdown `check --data-dir` exited 0
|
||||
> again.
|
||||
|
||||
## Port 53 is already taken
|
||||
|
||||
**Symptom.** The process exits 1, having named the socket it could not have:
|
||||
|
||||
```
|
||||
cannot bind udp [::1]:53: AddressInUse
|
||||
nxdns run failed: AddressInUse
|
||||
```
|
||||
|
||||
A bind conflict is a runtime failure, not a configuration fault, so this is exit 1 and `nxdns check` will not find it.
|
||||
|
||||
**Diagnosis.**
|
||||
|
||||
```sh
|
||||
ss -lnup 'sport = :53'
|
||||
ss -lntp 'sport = :53'
|
||||
systemctl is-active systemd-resolved
|
||||
```
|
||||
|
||||
On most systemd distributions the holder is `systemd-resolved`, which runs a stub listener on `127.0.0.53:53` and on some setups binds `0.0.0.0:53`.
|
||||
|
||||
**Fix.** Turn off the stub listener and keep resolved for the host's own lookups:
|
||||
|
||||
```sh
|
||||
mkdir -p /etc/systemd/resolved.conf.d
|
||||
printf '[Resolve]\nDNSStubListener=no\n' > /etc/systemd/resolved.conf.d/nxdns.conf
|
||||
systemctl restart systemd-resolved
|
||||
```
|
||||
|
||||
If `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/stub-resolv.conf`, repoint it at `/run/systemd/resolve/resolv.conf` so the host still resolves.
|
||||
|
||||
> Not verified on this host: this needs root, and `systemd-resolved` is
|
||||
> inactive here with port 53 free, so the conflict could not be reproduced
|
||||
> against it. The bind failure itself was reproduced by starting a second nxdns
|
||||
> on a port the first already held, which is the same error path.
|
||||
|
||||
Do not fix this by pointing the host's `/etc/resolv.conf` at nxdns when that host is where nxdns resolves its own upstream DoH and DoT hostnames. That is a startup cycle, not a fix.
|
||||
|
||||
## The container restarts in a loop
|
||||
|
||||
**Symptom.** `docker compose ps` shows the container restarting, and the log is the same failure repeated. Docker has no start limit, so this goes on forever.
|
||||
|
||||
```
|
||||
FAIL /etc/nxdns/config.zon: not readable
|
||||
nxdns run failed: ManagedConfigUnreadable
|
||||
```
|
||||
|
||||
**Diagnosis.**
|
||||
|
||||
```sh
|
||||
docker inspect -f '{{.State.Status}} exit={{.State.ExitCode}} restarts={{.RestartCount}}' docker-nxdns-1
|
||||
stat -c '%a %u:%g %n' deploy/docker/etc-nxdns/config.zon
|
||||
```
|
||||
|
||||
Exit 2 naming the configuration path means the container could not read the file the shipped `command:` makes its configuration. The container runs as uid 65532 and `/etc/nxdns` is mounted read-only, so a file at mode 0600 owned by your own uid is unreadable to it and the container cannot repair it.
|
||||
|
||||
**Fix.** Either make the file world-readable, when it holds no secret:
|
||||
|
||||
```sh
|
||||
chmod 0644 deploy/docker/etc-nxdns/config.zon
|
||||
```
|
||||
|
||||
or give it to the container's uid:
|
||||
|
||||
```sh
|
||||
chown 65532:65532 deploy/docker/etc-nxdns/config.zon
|
||||
chmod 0600 deploy/docker/etc-nxdns/config.zon
|
||||
```
|
||||
|
||||
The 0644 path was verified against an earlier revision of this page, including the recovery: after the `chmod` the container started and answered queries. The `chown` needs root and was not run here.
|
||||
|
||||
`FAIL /etc/nxdns/config.zon: no such file` instead of `not readable` means there is no configuration file at all. Create `deploy/docker/etc-nxdns/config.zon` and bring it up again; see [Install with Docker](install-with-docker.md).
|
||||
|
||||
A container that exits 2 with `NoUsableUpstreams` is in database mode — the `command:` line naming `--config` was removed — on a volume whose database is still empty. Load one and bring it back up:
|
||||
|
||||
```sh
|
||||
docker compose -f deploy/docker/compose.yaml run --rm nxdns import /etc/nxdns/config.zon
|
||||
```
|
||||
|
||||
> Not re-run on this host: staging a release image needs `zig build dist`, which
|
||||
> could not run here while the web bundle was mid-rebuild by other work in the
|
||||
> same checkout. The failure text quoted above is what the same binary prints
|
||||
> outside a container, which was reproduced here, with the container's paths.
|
||||
|
||||
## The admin interface refuses an edit with 403
|
||||
|
||||
**Symptom.** Saving anything in the admin interface fails, and the API answers:
|
||||
|
||||
```json
|
||||
{"error":"configuration is managed by /etc/nxdns/config.zon; edit the file and restart"}
|
||||
```
|
||||
|
||||
This is not a fault. The service runs `nxdns run --config`, which makes that file the configuration, and configuration writes through the API are refused so the file and the running server cannot drift apart.
|
||||
|
||||
**Diagnosis.** The start log names the authority:
|
||||
|
||||
```sh
|
||||
journalctl -u nxdns | grep 'authority:'
|
||||
```
|
||||
|
||||
```
|
||||
info(nxdns): authority: file (/etc/nxdns/config.zon)
|
||||
```
|
||||
|
||||
**Fix.** Edit the file, validate it, restart:
|
||||
|
||||
```sh
|
||||
$EDITOR /etc/nxdns/config.zon
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
systemctl restart nxdns
|
||||
```
|
||||
|
||||
Or, if you want the interface to be how this box is configured, leave file mode: drop `--config` from `ExecStart` and restart. The database already holds the last reconciled state, so nothing is lost. See [Run in file mode](install-with-systemd.md#run-in-file-mode).
|
||||
|
||||
Pausing blocking, refreshing blocklists and reloading certificates are not configuration and keep working in file mode. Deleting a client works too, unless the file names that client's address.
|
||||
|
||||
## The container cannot reach its upstreams
|
||||
|
||||
**Symptom.** The container starts, but every query fails and `nxdns check` inside it reports each upstream as unreachable.
|
||||
|
||||
**Diagnosis.** Look at what the host resolves with:
|
||||
|
||||
```sh
|
||||
cat /etc/resolv.conf
|
||||
```
|
||||
|
||||
**Fix.** If it points at the nxdns container, repoint it at a real resolver. The container resolves its upstream DoH and DoT hostnames through the host's DNS configuration, so pointing that at nxdns makes nxdns depend on itself to start. LAN clients point at nxdns; the container's own host does not.
|
||||
|
||||
## SERVFAIL in bursts, only under concurrent load
|
||||
|
||||
**Symptom.** Single queries answer normally, but a burst of unique names — a page load, a device waking up, a `dig` loop — returns SERVFAIL for some of them, and the upstream itself is healthy on `/api/health`.
|
||||
|
||||
**Diagnosis.** Scrape the queue counters:
|
||||
|
||||
```sh
|
||||
curl -s http://127.0.0.1:8080/metrics | grep nxdns_upstream_
|
||||
```
|
||||
|
||||
`nxdns_upstream_in_flight` against `nxdns_upstream_slots` is how much of an upstream's concurrency is in use right now, and `nxdns_upstream_queued_total` counts exchanges that had to wait for a slot (with `nxdns_upstream_queued_seconds_total` for how long they waited in total). Both queue counters are approximate — they are sampled when a query is admitted, not measured as a queue length. A `queued_total` climbing with each burst means queries are waiting on the upstream rather than failing at it, and a query that waits past `upstream.total_timeout_ms` is given up on in the queue and answered SERVFAIL. `nxdns_upstream_budget_exhausted_total` counts those give-ups pool-wide — queries whose own budget ran out, in the queue or mid-attempt, before any upstream answered. It carries no `url` label on purpose: running out of budget is a fact about the pool, so the exhausted attempt is never charged to an upstream's health and is never attributed in the query log, although the row can still name the last endpoint whose success or recorded failure preceded it.
|
||||
|
||||
`nxdns_upstream_reuse_recoveries_total` is the other half of the picture: it counts DoT connections that went stale between exchanges and were redialed. A few are normal — a resolver is free to close an idle connection. One per query means the connection is never being reused, and every query is paying a full TLS handshake.
|
||||
|
||||
**Fix.** Raise `upstream.total_timeout_ms` if the queue drains but drains too slowly for the budget. Otherwise the queue is telling you the upstream is slow: an upstream answering in a few milliseconds does not fill eight concurrent slots at household query rates, so sustained queueing points at the resolver you configured, and a faster one is the fix. Adding a second upstream helps only with saturation, not with latency: failover is strict priority, not load spreading. A query does take the next upstream when the first one's slots are all busy — priority orders the candidates that can be admitted right now — but once every eligible upstream is full it blocks on the highest-priority one, and it still sends one query to one upstream at a time. The per-upstream slot count is compiled, not configured, so there is no knob to widen one upstream either.
|
||||
|
||||
## SERVFAIL rows that name no upstream
|
||||
|
||||
**Symptom.** The query log shows SERVFAIL rows whose `upstream` is empty, and `/api/health` shows every upstream healthy.
|
||||
|
||||
**Diagnosis.** A failed exchange names no upstream only when no attributable attempt happened, and two pool-wide counters say why:
|
||||
|
||||
```sh
|
||||
curl -s http://127.0.0.1:8080/metrics | grep -E 'nxdns_upstream_(budget_exhausted|local_resource)_total'
|
||||
```
|
||||
|
||||
`nxdns_upstream_budget_exhausted_total` is a query whose own budget ran out first; the previous section covers it. `nxdns_upstream_local_resource_total` is an exchange this process ended on its own resources: out of memory, out of file descriptors, or a system error the runtime has no name for. Neither is charged to an upstream, because no upstream caused it, and a local failure does not fail over, because the next upstream would hit the same wall. Both count exchanges, not rows without an upstream: when an earlier upstream had already failed in the same exchange, the row names that one.
|
||||
|
||||
**Fix.** For `local_resource_total`, look at the process's limits: `grep -E 'Max open files' /proc/$(pidof nxdns)/limits` against `ls /proc/$(pidof nxdns)/fd | wc -l`, and `VmRSS` in `/proc/$(pidof nxdns)/status` against the memory the host has. A connect that fails for a reason the runtime cannot name — a blackhole route to the upstream is one — is not counted here: it is charged to that upstream as `ConnectFailed (cause Unexpected)`, and the query fails over.
|
||||
|
||||
## A DoH upstream fails with `HttpStatus (status 505 HTTP Version Not Supported)`
|
||||
|
||||
**Symptom.** Diagnostics shows the upstream failing with that cause, and no query ever succeeds against it.
|
||||
|
||||
**Diagnosis.** The server refuses HTTP/1.1. nxdns speaks DoH over HTTP/1.1 only, and some public resolvers (Quad9's `https://dns.quad9.net/dns-query`, for one) require HTTP/2. Other statuses name themselves the same way: a 403 or 404 is usually a wrong URL path.
|
||||
|
||||
**Fix.** Use that provider's DoT endpoint instead (for Quad9, `tls://9.9.9.9:853` with `tls_name = "dns.quad9.net"`), or a DoH upstream that accepts HTTP/1.1.
|
||||
|
||||
## The disk is filling up
|
||||
|
||||
**Symptom.** Writes stop but DNS keeps answering. The journal shows the transition:
|
||||
|
||||
```
|
||||
warning(disk_monitor): disk state ok -> critical: 33349095424 bytes free on /var/lib/nxdns
|
||||
```
|
||||
|
||||
**Diagnosis.**
|
||||
|
||||
```sh
|
||||
curl -s http://127.0.0.1:8080/api/health
|
||||
```
|
||||
|
||||
`/api/health` needs no login. It answers with five condition objects, and `status` is `degraded` when any one of them is in a degrading state:
|
||||
|
||||
```json
|
||||
{"status":"degraded","protection":{"state":"active","until":null},"upstreams":{"state":"ok","available":1,"total":1},"query_history":{"state":"recording","dropped_total":0,"last_drop_s":null},"diagnostics":{"state":"recording","active_warnings":1,"active_errors":0},"disk":{"state":"critical","free_bytes":33349079040}}
|
||||
```
|
||||
|
||||
The disk monitor's `warn` state is reported here as `low`, because `warn` reads as a log level rather than as a quantity of disk.
|
||||
|
||||
`/metrics` carries the free, database and log byte gauges as `nxdns_disk_free_bytes`, `nxdns_disk_db_bytes` and `nxdns_disk_log_bytes`, and counts gated refreshes as `nxdns_blocklist_refreshes_gated_total`. The disk state itself is on `/api/health`, not in the metrics output.
|
||||
|
||||
**What the state means.** The monitor samples free space and database sizes once a minute. Below `disk.warn_free_mb` it logs the transition. Below `disk.min_free_mb` it gates every non-essential write: the query logger holds its batches, the client tracker stops persisting, and blocklist refreshes are skipped and counted in `nxdns_blocklist_refreshes_gated_total`. A gate that has already cost query rows shows as `query_history.state = "losing"`. Resolution never degrades because the disk is full — this was verified by setting the thresholds above the free space on the volume: the state went critical, a refresh was gated, and queries kept being answered.
|
||||
|
||||
**Fix.** Recover space — lower `logging.retention_days`, or stop the service and delete `querylog.db` — and writes resume on the next sample.
|
||||
|
||||
## Blocklists are not filtering
|
||||
|
||||
**Symptom.** Domains that should be blocked resolve normally.
|
||||
|
||||
**Diagnosis.** Read the startup line:
|
||||
|
||||
```sh
|
||||
journalctl -u nxdns | grep 'serving on'
|
||||
```
|
||||
|
||||
It ends in either `blocklist generation N` or `unfiltered (no blocklist snapshot)`.
|
||||
|
||||
**Fix.** `unfiltered` means no snapshot loaded at all; the download or compile warning that explains it is earlier in the same start. nxdns serves anyway on purpose — a household loses more from DNS that refuses to start than from a window of unfiltered answers.
|
||||
|
||||
A generation number with nothing being blocked is a different problem: the snapshot loaded but has no sources in it. The line `blocklist snapshot generation 1: 0 of 0 sources loaded` says exactly that. Add a source in the admin interface, or a `blocklist_sources` entry to the configuration file with a `group_sources` link naming a group.
|
||||
|
||||
One name resolving while its neighbours are blocked is a third case, and `/api/lookup` answers it directly: it reports which level of the filtering ladder decided, and against what.
|
||||
|
||||
```sh
|
||||
curl -s 'http://127.0.0.1:8080/api/lookup?domain=api.ads.tvb.com'
|
||||
```
|
||||
|
||||
```json
|
||||
{"domain":"api.ads.tvb.com","group_id":1,"local_records":false,"forward_zone":null,"blocked":false,"reason":"blocklist_exception","matched":"api.ads.tvb.com","source_url":"https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt","safe_search_rewrite":null}
|
||||
```
|
||||
|
||||
`blocklist_exception` means a downloaded list lifted that name with an `@@` line, and `source_url` names the list that did it. Nothing is broken, and the list is not overruling you: an exception cancels only what another list blocks. Your own rule wins over it. Adding an exact block rule for the same name and asking again reports `rule_block_exact`, `blocked` true and a null `source_url`.
|
||||
|
||||
## A database stamped by a newer binary
|
||||
|
||||
**Symptom.** After putting an older binary back, it will not start:
|
||||
|
||||
```
|
||||
warning(migrations): config.db is at schema version 99; this nxdns binary supports 1
|
||||
nxdns run failed: SchemaTooNew
|
||||
```
|
||||
|
||||
**Fix.** There is no downgrade. Import the export you took before upgrading into a fresh data directory with the older binary; see [Upgrade nxdns](upgrade.md).
|
||||
|
||||
## The server refuses to start over querylog.db
|
||||
|
||||
**Symptom.** The process stops at startup naming the query log, and the error is one of four names:
|
||||
|
||||
```
|
||||
error(querylog_schema): refusing to open querylog database '/var/lib/nxdns/querylog.db': it is stamped 7, and this build supports schema versions 1 to 1 (SchemaTooNew). The file is left exactly as it is; see docs/how-to/troubleshoot.md, "The server refuses to start over querylog.db"
|
||||
nxdns run failed: SchemaTooNew
|
||||
```
|
||||
|
||||
This is a refusal, not damage. nxdns will not replace a healthy query log to get itself started, so the file is left exactly as it was — schema, rows, coverage watermark and version stamp all unchanged — and the startup fails instead. All four exit 2, the code that means an operator has to act, because none of them resolves on a retry — the shipped systemd unit's `RestartPreventExitStatus=2 64` stops the unit on the first refusal instead of restart-looping it. `systemctl status nxdns` shows the refusal. `nxdns check` does not grade the query log at all, so it will not reproduce any of these.
|
||||
|
||||
[The query-log lifecycle](../reference/query-log-lifecycle.md) is the full contract behind this page.
|
||||
|
||||
**Fixes by name.**
|
||||
|
||||
- `SchemaTooNew` — the file was stamped by a newer nxdns than the one you are running, which normally means a binary was rolled back. Put the newer release back and start it: the file is exactly as that release left it. If you mean to stay on the older release, that release cannot read this file, so restore the `querylog.db.pre-migrate-<unix-seconds>` copy the upgrade left beside it — stop the server, move `querylog.db` and its `querylog.db-wal` and `querylog.db-shm` out of the way, rename the backup to `querylog.db`, and start. Starting empty is also an option: with the server stopped, move `querylog.db` and both sidecars aside and the next start creates a fresh log.
|
||||
- `SchemaUnsupported` — the stamp is not a version this build can reach. Either the file predates 0.0.12, or it came from somewhere else, or a release since deliberately broke the schema; the changelog section for the release you are running says so when it is the third case. There is no migration path, by contract. Keep the file if the history matters — copy it somewhere and read it with the `sqlite3` shell — and if starting with an empty log is acceptable, stop the server, move `querylog.db`, `querylog.db-wal` and `querylog.db-shm` out of the data directory by hand, and start again.
|
||||
- `MigrationBackupFailed` — a migration was due and the pre-migration backup could not be written, so nothing was migrated. The line above names the destination and the reason, which is almost always a full or read-only data directory. Free space or fix the permissions and start again.
|
||||
- `MigrationFailed` — read the log line above it, because two different states wear this one name.
|
||||
|
||||
**Which `MigrationFailed` you have.** The distinction is in the line the migration logged, and it decides whether you do anything at all:
|
||||
|
||||
- Before the commit: `querylog migration 1 -> 2 failed before commit (...); the database is unchanged`. Nothing was applied. The file still carries its old version and every row, and this run's backup was deleted because the original is intact. Restarting will attempt the same migration and fail the same way, so this needs the underlying cause — the log line names it — or a report.
|
||||
- After the commit: `querylog migration 1 -> 2 COMMITTED and the database IS at version 2, but the connection could not be restored: ...; the backup '...' is kept and the next start will open the migrated file normally`. The migration DID complete. Only that one startup is refused, the pre-migration backup is kept, and the next start opens the migrated file on the ordinary current-version path. Start the server again.
|
||||
|
||||
In neither case does the server start with an empty log on its own. Recreating a query log automatically is reserved for real corruption; see [why a query log is moved aside](../reference/files-and-directories.md#why-a-query-log-is-moved-aside).
|
||||
|
||||
> Not reproduced against a running service: the four refusals are covered by the
|
||||
> test suite rather than by a hand-driven install, and the released chain has no
|
||||
> migration step in it yet, so no upgrade produces a `pre-migrate` backup today.
|
||||
> The messages above are the ones `src/storage/querylog_schema.zig` and
|
||||
> `src/storage/querylog_migrations.zig` emit, with a data directory path and
|
||||
> example version numbers filled in.
|
||||
+45
-314
@@ -1,376 +1,107 @@
|
||||
# Upgrade nxdns
|
||||
# Upgrade
|
||||
|
||||
Replaces a running nxdns with a newer release without losing its configuration. The database is migrated in place on the first start of the new binary.
|
||||
Move a running nxdns to a newer release without losing its configuration or its history. The new binary upgrades the databases in place the first time it starts.
|
||||
|
||||
The normal path is to download the new release, verify it, and swap the binary. Upgrading a build you made yourself is the last section of this page.
|
||||
## 1. Read the release notes
|
||||
|
||||
> Verification: the export, the migration behaviour and the `version`/`check`
|
||||
> steps below were run on the machine that wrote this page, against a
|
||||
> populated scratch data directory and with an explicit `--data-dir`, since
|
||||
> that machine has no `/var/lib/nxdns`. The commands were not run exactly as
|
||||
> printed — the page uses the defaults and placeholders a real operator would
|
||||
> have (`/var/lib/nxdns`, `/some/backup`, a `target` host), and every block
|
||||
> where the substitution matters, or which was not run at all, carries its own
|
||||
> note. Nothing here was verified except where a note says so.
|
||||
>
|
||||
> The download in step 2 was run on 2026-10-02 against the published `v0.0.21` release; its note carries the detail.
|
||||
Each release's notes are its section of the [changelog](../../CHANGELOG.md). nxdns is not at 0.1 yet, and a release can still change behaviour or settings on purpose; the notes say what changed and what to do about it.
|
||||
|
||||
## Breaking change: `run --config` now means file authority
|
||||
## 2. Take a backup
|
||||
|
||||
**Read this before upgrading if anything on your box passes `--config` to `nxdns run`** — a systemd drop-in, a wrapper script, or a `command:` in a compose file.
|
||||
|
||||
`run --config FILE` used to mean *seed once*: the file was read only while the database was still empty, and ignored on every start after that. It now means *the file is the configuration*: every start reconciles the database onto it.
|
||||
|
||||
For a box that was seeded once and then configured through the admin interface, the first start after the upgrade converges the database back to that old seed file. **Every change made through the UI since seeding is deleted.**
|
||||
|
||||
There are two ways out, and you pick before you restart:
|
||||
|
||||
- **Keep the database.** Drop the flag. `nxdns run` with no `--config` serves the database exactly as it did before, and nothing reads a file. This is the right answer if the UI is how you change things.
|
||||
- **Adopt file mode cleanly.** Install the new binary, stop the service, export the current database over the file path, check it, then start with the flag. The first reconcile is then a no-op, because the file was rendered from the database it governs. **Install the new binary first** — see the order trap below. The full procedure is [Adopt file mode](install-with-systemd.md#adopt-file-mode-on-a-box-that-is-already-running).
|
||||
|
||||
`nxdns check --config FILE` is unchanged: it graded that file before and it grades that file now.
|
||||
|
||||
### The order trap: export with the new binary, not the old one
|
||||
|
||||
Take the export **after** you have replaced the binary, with the service stopped. Exporting first — the instinctive order, and the one step 1 of this page tells you to take for a backup — produces a file the new binary refuses.
|
||||
|
||||
A 0.0.1 `nxdns export` writes both fields:
|
||||
|
||||
```zon
|
||||
.password = "",
|
||||
.password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…",
|
||||
```
|
||||
|
||||
An empty `password_hash` used to mean "unset". It now means "disable authentication", so it is a *present* value — and a file that carries both fields states two different things about the password and is refused:
|
||||
|
||||
```
|
||||
FAIL web.password: password and password_hash are both set; ambiguity in a security setting is refused
|
||||
FAIL web.password: password is set to the empty string; omit the field to keep the stored password, or set password_hash = "" to disable authentication
|
||||
nxdns run failed: PasswordAndHashBothSet
|
||||
```
|
||||
|
||||
The old `nxdns check` passes that file, because the old binary agreed with the old rule. So the failure lands at the first start after the upgrade, with the resolver stopped and the unit refusing to retry it (`RestartPreventExitStatus=2 64`). A new `nxdns export` writes `.password = null` instead and has no such problem.
|
||||
|
||||
**If you already have an old export you want to adopt**, you do not need to redo it. Delete the empty-password line and the file is valid:
|
||||
In database mode, export the configuration first:
|
||||
|
||||
```sh
|
||||
sed -i '/^ \.password = "",$/d' /etc/nxdns/config.zon
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
nxdns export --out /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
Keep the `.password_hash` line — that is the password, and deleting it as well would leave the file saying nothing about authentication, which means "keep whatever is stored" rather than anything you would notice.
|
||||
The export is written at mode 0600 and carries the admin password's hash, so keep it as private as the database. In file mode your configuration file is already the backup. [Back up and restore](back-up-and-restore.md) has the details.
|
||||
|
||||
The same trap has nothing to do with file mode as such: it is any 0.0.1 export fed to the new binary, so it also applies to a restore through `nxdns import`. Backups taken with 0.0.1 need that one line removed before they will load.
|
||||
|
||||
> Verified on this host, with one substitution stated: the repository has no
|
||||
> 0.0.1 binary to hand, so the old export was **simulated** by taking a current
|
||||
> `nxdns export` and rewriting `.password = null` to `.password = ""`, which is
|
||||
> the one byte-level difference between the two formats. Against that file,
|
||||
> `nxdns check --config` printed both FAIL lines above and exited 2, and
|
||||
> `nxdns run --config` printed them and failed `PasswordAndHashBothSet`. After
|
||||
> the `sed` above, `nxdns check --config` exited 0 with `OK: no problems found`
|
||||
> and `nxdns import` of the same file exited 0, keeping the hash. The claim
|
||||
> about what 0.0.1's `export` emitted is read from that release's source —
|
||||
> `git show v0.0.1:src/config/export.zig` line 71 is `cfg.web.password = "";` —
|
||||
> not from running that binary.
|
||||
|
||||
A database-mode install that never passed `--config` needs nothing. Under Docker, a fresh database-mode install must either take the new compose file or run `import` once — see [Database mode in Docker](install-with-docker.md#database-mode-in-docker-instead).
|
||||
|
||||
Two smaller renames in the same release: `nxdns import --force` is now `--allow-delete`, and it is required only when the file's diff would delete rows rather than whenever the database is non-empty. `nxdns check` no longer falls back to a default file path when there is no database; it reports the absent database and names the two ways to get one.
|
||||
|
||||
There is no schema migration in this change.
|
||||
|
||||
## 1. Take an export first
|
||||
|
||||
There is no downgrade path, so the export is what you fall back to:
|
||||
|
||||
```sh
|
||||
nxdns export --out /some/backup/nxdns-config.zon
|
||||
```
|
||||
|
||||
`/some/backup` is a stand-in for a directory you keep backups in, and the command relies on the default `--data-dir /var/lib/nxdns` that a systemd install has.
|
||||
|
||||
This export is a fallback, not a file to deploy. If you are adopting file mode, take a *second* export after the binary swap and use that one — an export written by 0.0.1 carries a `.password = ""` line the new binary refuses, as [the order trap](#the-order-trap-export-with-the-new-binary-not-the-old-one) explains. The same line has to come out of this backup before the new binary will import it.
|
||||
|
||||
> Verified on this host with both paths substituted, since it has neither
|
||||
> `/var/lib/nxdns` nor `/some/backup`. `SCRATCH` below is a scratch directory,
|
||||
> and its `data/` was populated beforehand with `nxdns import`:
|
||||
>
|
||||
> ```
|
||||
> $ nxdns export --data-dir $SCRATCH/data --out $SCRATCH/nxdns-config.zon
|
||||
> wrote /…/scratchpad/nxdns-config.zon
|
||||
> $ stat -c '%a %n' $SCRATCH/nxdns-config.zon
|
||||
> 600 /…/scratchpad/nxdns-config.zon
|
||||
> $ grep password $SCRATCH/nxdns-config.zon
|
||||
> .password = "",
|
||||
> .password_hash = "$argon2id$v=19$m=19456,t=2,p=1$mCNEo…$i3DMz…",
|
||||
> ```
|
||||
>
|
||||
> The shell umask was 022, so the 0600 is `export` setting it, not the umask.
|
||||
> Only the two paths differ from the command above.
|
||||
|
||||
The file is written atomically at mode 0600 and carries `web.password_hash`, so treat it as a secret. See [Back up and restore](back-up-and-restore.md) for the full backup story. The query log is deliberately not part of it.
|
||||
|
||||
## 2. Download and verify the new release
|
||||
|
||||
Read the release notes for the version you are moving to before you take it — the `CHANGELOG.md` section for that version is the release body.
|
||||
|
||||
```sh
|
||||
BASE=https://git.mial.net/mokhtar/nxdns
|
||||
VERSION=$(curl -fsS -o /dev/null -w '%{redirect_url}' "$BASE/releases/latest" |
|
||||
sed 's#.*/releases/tag/v##')
|
||||
mkdir -p ~/nxdns-release && cd ~/nxdns-release
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/nxdns-$VERSION-x86_64-linux-musl.tar.gz"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt.asc"
|
||||
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
|
||||
sha256sum -c --ignore-missing SHA256SUMS.txt
|
||||
tar -xzf "nxdns-$VERSION-x86_64-linux-musl.tar.gz"
|
||||
```
|
||||
|
||||
The first line asks the server which release is current, so this block does not carry a version number that goes stale — Gitea redirects `releases/latest` to the newest published release's tag page. To move to a particular version rather than the newest, set `VERSION=<version>` yourself. Check it against what you are running (`nxdns version`) before you download anything.
|
||||
|
||||
Take `aarch64-linux-musl` for a Raspberry Pi 5. Verify every time, not only on the first install — an upgrade is a fresh download of a fresh artifact. [Verify a release](verify-a-release.md) is the full procedure.
|
||||
|
||||
Under Docker there is nothing to download: step 3 pulls the image, and the `IMAGE-DIGEST.txt` asset is what you verify instead.
|
||||
|
||||
> Verified on 2026-10-02 against `v0.0.21`: the lookup printed `0.0.21`, every `curl` succeeded, `gpg --verify` printed `Good signature`, `sha256sum -c` printed `OK`, and the tarball extracted. [Install with systemd](install-with-systemd.md) has the detail.
|
||||
|
||||
## 3. Replace the binary
|
||||
## 3. Replace nxdns
|
||||
|
||||
### systemd
|
||||
|
||||
Step 2 leaves the new binary in the extracted directory. Copy the one that matches the host — `aarch64-linux-musl` for a Raspberry Pi 5:
|
||||
Download and verify the new release as in [Install with systemd](install-with-systemd.md#1-download-and-verify), taking `aarch64` for a Raspberry Pi. Then, as root, from the unpacked directory:
|
||||
|
||||
```sh
|
||||
scp "nxdns-$VERSION-x86_64-linux-musl/nxdns" target:/tmp/nxdns
|
||||
```
|
||||
|
||||
> Not run on this host: `target` is a placeholder for the machine running
|
||||
> nxdns, and this host has no such second machine to copy to. There is also no
|
||||
> release to have extracted.
|
||||
|
||||
The tarball also carries `nxdns.service` and `nxdns.conf`. An upgrade does not normally reinstall them, but compare them against what is on the target when the release notes say the unit changed.
|
||||
|
||||
Then, as root on the target:
|
||||
|
||||
```sh
|
||||
install -m 0755 /tmp/nxdns /usr/local/bin/nxdns
|
||||
install -m 0755 nxdns /usr/local/bin/nxdns
|
||||
systemctl restart nxdns
|
||||
journalctl -u nxdns -f
|
||||
```
|
||||
|
||||
> Not run on this host: all three lines need root and an installed service.
|
||||
> The migration half of what a restart does is checkable without either, and
|
||||
> was — see the note under
|
||||
> [What happens to the database](#what-happens-to-the-database). The swap of
|
||||
> an older binary for a newer one on a live service was not reproduced here.
|
||||
The tarball also carries `nxdns.service` and `nxdns.conf`. Reinstall them only when the release notes say they changed.
|
||||
|
||||
### Docker
|
||||
|
||||
The compose file names the release it belongs to, so upgrading the image is upgrading the file. A new release's compose file can change more than the image — the `command:` line or a port — so both ways below replace yours: if you edited it by hand, carry your edits over to the new one. To keep your own file as it is, skip the `curl` or the `git checkout` and set `NXDNS_VERSION=$VERSION` on the `pull` and `up` lines instead: it overrides the release the file names. A compose file from `v0.0.22` or earlier defaults to `:latest`, so with one of those the variable is needed on both lines, or `pull` and `up` can land on different images if a release happens between them.
|
||||
|
||||
With the single downloaded file of [Install with Docker](install-with-docker.md), fetch the new release's copy over it in its directory, then pull and recreate:
|
||||
The compose file names the release it belongs to, so fetch the new release's copy over yours, then pull and recreate the container:
|
||||
|
||||
```sh
|
||||
cd ~/nxdns
|
||||
curl -fLO "$BASE/raw/tag/v$VERSION/deploy/docker/compose.yaml"
|
||||
curl -fLO https://git.mial.net/mokhtar/nxdns/raw/tag/v<version>/deploy/docker/compose.yaml
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
With a checkout of the repository, fetch the tag and move to it, from the repository root:
|
||||
If you edited your compose file, carry your edits over to the new one. To keep your file exactly as it is, skip the `curl` and set the release on both commands instead: `NXDNS_VERSION=<version> docker compose pull`, then `NXDNS_VERSION=<version> docker compose up -d`.
|
||||
|
||||
```sh
|
||||
git fetch origin tag "v$VERSION"
|
||||
git checkout "v$VERSION"
|
||||
docker compose -f deploy/docker/compose.yaml pull
|
||||
docker compose -f deploy/docker/compose.yaml up -d
|
||||
```
|
||||
The container is recreated on the same `nxdns-data` volume, so the configuration and history stay.
|
||||
|
||||
Compose recreates the container against the same `nxdns-data` volume. What happens to the file in `etc-nxdns` depends on the `command:` in your compose file: with the shipped `run --config=/etc/nxdns/config.zon` the file is the configuration and the restart reconciles onto it; without it, the database in the volume is the configuration and the file is read by nothing.
|
||||
### Nix
|
||||
|
||||
> Not run on this host: `pull` and `up` were not run against a new release.
|
||||
> What was run on 2026-10-20 is `docker compose -f deploy/docker/compose.yaml
|
||||
> config` on a tree whose `build.zig.zon` declares `0.0.22`, which resolves
|
||||
> the variables without contacting a registry: no variable gave
|
||||
> `image: git.mial.net/mokhtar/nxdns:0.0.22`, and `NXDNS_VERSION=0.0.21` gave
|
||||
> `image: git.mial.net/mokhtar/nxdns:0.0.21`.
|
||||
> The fetch half was run the same day against `v0.0.22`: the `curl` URL
|
||||
> returned 200, and `git fetch --dry-run origin tag v0.0.22` exited 0.
|
||||
Change the tag in the flake input and switch; see [Install with Nix](install-with-nix.md#3-upgrade).
|
||||
|
||||
## 4. Confirm the upgrade
|
||||
## 4. Confirm
|
||||
|
||||
```sh
|
||||
nxdns version
|
||||
nxdns export --out /tmp/after-upgrade.zon
|
||||
nxdns check --config /tmp/after-upgrade.zon
|
||||
dig @127.0.0.1 example.com A +short
|
||||
```
|
||||
|
||||
The restart in step 3 is what migrated the database, so by now the schema is current and the service is answering. Confirming with `nxdns check` alone would not work here, and the reason is worth knowing: `check` opens `config.db` immutable so it can never write to it, and the migration you just performed is sitting in `config.db-wal` waiting to be checkpointed. Rather than read around the log and grade older settings, `check` reports it:
|
||||
`version` prints the release you installed. The start log names it too:
|
||||
|
||||
```
|
||||
FAIL /var/lib/nxdns/config.db: uncheckpointed changes are waiting in /var/lib/nxdns/config.db-wal, and reading without writing would answer from the older settings in the main file; `nxdns run` applies them. A running nxdns normally holds this log, which is the usual reason to see this line.
|
||||
info(nxdns): nxdns <version> serving on udp [::]:53 tcp [::]:53 tcp 0.0.0.0:53; 1 upstream(s); blocklist generation 1
|
||||
```
|
||||
|
||||
`export` opens the database read/write and does see the log, so exporting and then checking the export validates what is actually in force:
|
||||
## What happens to the databases
|
||||
|
||||
```
|
||||
checking configuration file /tmp/after-upgrade.zon
|
||||
OK upstreams[0] https://cloudflare-dns.com
|
||||
OK: no problems found
|
||||
```
|
||||
|
||||
> Verified on this host for the first three commands, with `--data-dir`
|
||||
> pointing at a scratch data directory instead of `/var/lib/nxdns` — that path
|
||||
> is the only difference from the blocks above:
|
||||
>
|
||||
> ```
|
||||
> $ nxdns version
|
||||
> nxdns <version>
|
||||
> zig 0.16.0
|
||||
> ```
|
||||
>
|
||||
> Against a running server whose database had just taken a configuration write
|
||||
> through the API, `nxdns check --data-dir` printed the uncheckpointed-log line
|
||||
> above and exited 2, while `nxdns export --out` followed by
|
||||
> `nxdns check --config` on the result exited 0 with `OK: no problems found`.
|
||||
> Both were re-run for this revision. The `dig` line was not run in this round:
|
||||
> nothing is listening on 127.0.0.1:53 here, and port 53 needs root.
|
||||
|
||||
## What happens to the database
|
||||
|
||||
Migrations run at startup, and also before `export` and `import`, so whichever of those you run first performs the upgrade. `nxdns check` is the exception: it opens the database immutable and never migrates, so on a database still one version behind it reports the mismatch and exits 2 rather than fixing it:
|
||||
|
||||
```
|
||||
FAIL /var/lib/nxdns/config.db: schema version 0, this nxdns expects 1; `nxdns run` migrates it, `check` will not
|
||||
```
|
||||
|
||||
That line was reproduced here against a database stamped at version 0; the path and the version numbers are what vary.
|
||||
|
||||
A fresh database is created at the current schema version; an older one is stepped up to it. The log line names both versions:
|
||||
A release that changes how data is stored upgrades `config.db` and `querylog.db` when it first starts, and logs it:
|
||||
|
||||
```
|
||||
info(migrations): config.db migrated from schema version 0 to 1
|
||||
```
|
||||
|
||||
> Verified on this host: that exact line is what `nxdns import` printed when it
|
||||
> created the scratch database used throughout this page. An empty data
|
||||
> directory is schema version 0, which is why a first run reports a migration
|
||||
> rather than nothing. Version 1 is the only schema nxdns has published, so an
|
||||
> upgrade from a populated older one is not a case that exists yet.
|
||||
Before it upgrades the query history, nxdns copies it to `querylog.db.pre-migrate-<unix-seconds>` beside the original and keeps that copy. An upgrade either completes or leaves the file as it was; if it fails, nxdns refuses to start and says so, and the history is untouched.
|
||||
|
||||
Rolling back is the case that has no answer. A database stamped by a newer binary refuses to open, so an older binary against an upgraded data directory fails to start:
|
||||
A release can also be unable to convert the old query history. Its release notes then say `resets your query history` and explain how to keep the old file. That release refuses to start until you move the old file aside, and its message says how; [Files and directories](../reference/files-and-directories.md#the-query-history-database) has the commands.
|
||||
|
||||
## Going back to an older release
|
||||
|
||||
Upgrades only go forward. An older nxdns refuses a database a newer one has already upgraded, and exits 2:
|
||||
|
||||
```
|
||||
warning(migrations): config.db is at schema version 99; this nxdns binary supports 1
|
||||
nxdns run failed: SchemaTooNew
|
||||
```
|
||||
|
||||
> Reproduced on this host, with one substitution: no binary from the future was
|
||||
> available, so the scratch database's `schema_version` row was set to 99 by
|
||||
> hand and `nxdns run` was pointed at it. The two lines above are that run's
|
||||
> output.
|
||||
|
||||
That run exits 2, and the shipped unit stops rather than restart-loops it. Recovering means importing the export you took in step 1 into a fresh data directory with the older binary.
|
||||
|
||||
### Rolling back from file mode
|
||||
|
||||
Putting an older binary back needs no unit edit. The old binary accepts `run --config` — it just reads it as the old seed-once flag — and against a database that already holds configuration it ignores the file entirely and serves the last state the new binary reconciled. So the service comes back up on the configuration it was running.
|
||||
|
||||
The consequence is worth stating plainly: **file edits stop applying.** The old binary will not re-read the file, so every change made to `config.zon` after the rollback does nothing at all, silently, until the newer binary is back. If you have to stay on the old binary, use `nxdns import` to apply file changes, or drop the flag so the invocation matches what the binary actually does.
|
||||
|
||||
The schema note above still governs: a database stamped by a newer binary refuses to open, whatever mode either binary runs in.
|
||||
|
||||
## Changing settings, not the binary
|
||||
|
||||
How you change a setting depends on which authority the service runs under. `nxdns run` in `ExecStart` means the database; `nxdns run --config FILE` means the file. The start log names it either way:
|
||||
|
||||
```
|
||||
info(nxdns): authority: database
|
||||
info(nxdns): authority: file (/etc/nxdns/config.zon)
|
||||
```
|
||||
|
||||
**In file mode**, edit the file, validate it, restart. The admin interface will refuse the change with a 403 naming the file, so there is nothing to get wrong:
|
||||
To go back anyway, install the older `nxdns` and give it a fresh data directory with the configuration you exported in step 2. As root:
|
||||
|
||||
```sh
|
||||
$EDITOR /etc/nxdns/config.zon
|
||||
nxdns check --config /etc/nxdns/config.zon
|
||||
systemctl restart nxdns
|
||||
```
|
||||
|
||||
**In database mode**, change settings through the admin interface, through the API, or with an export–edit–import cycle against a stopped server:
|
||||
|
||||
```sh
|
||||
nxdns export --out config-backup.zon
|
||||
$EDITOR config-backup.zon
|
||||
systemctl stop nxdns
|
||||
nxdns import config-backup.zon
|
||||
mv /var/lib/nxdns /var/lib/nxdns.newer
|
||||
nxdns import /var/backups/nxdns-config.zon
|
||||
```
|
||||
|
||||
If the upgrade converted the query history, nxdns kept a copy of it from before; restore that copy to keep the history:
|
||||
|
||||
```sh
|
||||
cp /var/lib/nxdns.newer/querylog.db.pre-migrate-* /var/lib/nxdns/querylog.db
|
||||
```
|
||||
|
||||
Then hand the directory to the service and start it:
|
||||
|
||||
```sh
|
||||
chown -R nxdns:nxdns /var/lib/nxdns
|
||||
systemctl start nxdns
|
||||
```
|
||||
|
||||
`import` needs no flag to add rows or to edit them. It needs `--allow-delete` only when applying the file would delete rows the database holds — including the case where you renamed something, since changing a group's name or an upstream's URL is a delete and an insert to the engine, not an edit. The refusal names the tables and rolls back:
|
||||
|
||||
```
|
||||
FAIL import: this file would delete rows the database holds (upstreams 1); re-run with --allow-delete to apply it
|
||||
import failed: DestructiveImport
|
||||
```
|
||||
|
||||
Stop the server first either way. `import` rewrites configuration underneath a process that read it at startup, and a running server picks up only some of it.
|
||||
|
||||
> Verified on this host against a populated scratch data directory, with
|
||||
> `--data-dir` pointing at it — that path is the only difference from the blocks
|
||||
> above:
|
||||
>
|
||||
> ```
|
||||
> $ nxdns import $SCRATCH/etc/config.zon --data-dir $SCRATCH/dbmode
|
||||
> imported /…/config.zon
|
||||
> (exit 0)
|
||||
> $ nxdns import $SCRATCH/etc/smaller.zon --data-dir $SCRATCH/dbmode
|
||||
> FAIL import: this file would delete rows the database holds (upstreams 1); re-run with --allow-delete to apply it
|
||||
> import failed: DestructiveImport
|
||||
> (exit 2)
|
||||
> $ nxdns import $SCRATCH/etc/smaller.zon --data-dir $SCRATCH/dbmode --allow-delete
|
||||
> imported /…/smaller.zon
|
||||
> (exit 0)
|
||||
> ```
|
||||
>
|
||||
> The first of those three is the additive case that needs no flag; the second
|
||||
> file replaced the upstream, which is an identity change and therefore a
|
||||
> delete. The `systemctl stop`/`start` lines need root and an installed service
|
||||
> and were not run; `$EDITOR` is yours to run.
|
||||
|
||||
## Upgrading to a build of your own
|
||||
|
||||
If you are running something you built rather than a release, step 2 is a build instead of a download:
|
||||
|
||||
```sh
|
||||
(cd admin && npm ci && npm run build)
|
||||
VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
|
||||
zig build dist -Dversion-string="$VERSION" \
|
||||
-Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
|
||||
```
|
||||
|
||||
Rebuild `admin/dist` before the binary on every upgrade. The admin interface is embedded at build time, and an old bundle against a new API is a broken System page. `dist` refuses the `admin/dist-placeholder` default outright, so the only way to ship a stale bundle is to leave an old `admin/dist` in place.
|
||||
|
||||
The staged payload for each target is under `zig-out/dist/stage/nxdns-<version>-<triple>/`, and step 3 continues from there with that path in place of the extracted one. The version string has to equal `.version` in `build.zig.zon` — `verify-dist` asserts it, so a made-up one builds and then fails verification. Your build reports the same two lines as the published release of that version, so compare the tarball hashes rather than the `nxdns version` output when you need to tell them apart.
|
||||
|
||||
Under Docker, build the image and name it instead of pulling:
|
||||
|
||||
```sh
|
||||
DOCKER_BUILDKIT=1 docker build -t nxdns -f deploy/docker/Dockerfile .
|
||||
NXDNS_IMAGE=nxdns docker compose -f deploy/docker/compose.yaml up -d
|
||||
```
|
||||
|
||||
See [Install with Docker](install-with-docker.md) for what that build needs.
|
||||
|
||||
> Verified on this host for the two build commands in this section — the
|
||||
> `zig build dist` block above and the `docker build` here. `dist` was run to
|
||||
> completion with the version read out of `build.zig.zon` and exited 0, and the
|
||||
> image was built from the resulting `zig-out/dist` tree, also exiting 0. The
|
||||
> `docker compose ... up -d` line was not run in this round — the run itself is
|
||||
> covered in [Install with Docker](install-with-docker.md#3-run-it), where a
|
||||
> host port had to be moved to do it. See
|
||||
> [Install with systemd](install-with-systemd.md#build-from-source-instead) for
|
||||
> the `dist` and `verify-dist` detail.
|
||||
Blocklists download again on the first start. Anything recorded after the upgrade stays in `/var/lib/nxdns.newer`.
|
||||
|
||||
+62
-207
@@ -1,91 +1,37 @@
|
||||
# Verify a release
|
||||
|
||||
Checks that a downloaded nxdns release is the one the project published and that it arrived intact. It also gives the recipe for rebuilding the same version from source, and says plainly what that does and does not settle.
|
||||
|
||||
Do this before you run the binary, not after. The whole point of the checksum file is that it is signed, so a tampered mirror cannot hand you a matching tarball and a matching checksum at the same time.
|
||||
|
||||
> Verification: every command on this page was run on 2026-08-09 against the
|
||||
> published `v0.0.1` release, from a clean directory, with a clean `GNUPGHOME`
|
||||
> holding only the key fetched from keys.openpgp.org. Every transcript below is
|
||||
> that run's output. Where a block shows a failure — a `BAD signature`, a
|
||||
> `FAILED` hash — the failure was produced deliberately by tampering with a
|
||||
> copy of the real file, and the surrounding text says how.
|
||||
Check that an nxdns release you downloaded is the one the project published, and that it arrived intact. Do it before you run the binary.
|
||||
|
||||
## What a release contains
|
||||
|
||||
Five assets, on the release page at `https://git.mial.net/mokhtar/nxdns/releases`:
|
||||
The [release page](https://git.mial.net/mokhtar/nxdns/releases) has five files for each version:
|
||||
|
||||
| Asset | What it is |
|
||||
| File | What it is |
|
||||
| --- | --- |
|
||||
| `nxdns-<version>-x86_64-linux-musl.tar.gz` | The x86_64 tarball |
|
||||
| `nxdns-<version>-aarch64-linux-musl.tar.gz` | The aarch64 tarball, for a Raspberry Pi 5 |
|
||||
| `SHA256SUMS.txt` | One `sha256sum` line each for the two tarballs and for `IMAGE-DIGEST.txt` |
|
||||
| `SHA256SUMS.txt.asc` | A detached OpenPGP signature over `SHA256SUMS.txt` |
|
||||
| `IMAGE-DIGEST.txt` | The container image reference this version pushed, pinned by digest |
|
||||
| `nxdns-<version>-x86_64-linux-musl.tar.gz` | nxdns for x86_64 Linux |
|
||||
| `nxdns-<version>-aarch64-linux-musl.tar.gz` | nxdns for 64-bit ARM Linux, such as a Raspberry Pi |
|
||||
| `SHA256SUMS.txt` | The SHA-256 of both tarballs and of `IMAGE-DIGEST.txt` |
|
||||
| `SHA256SUMS.txt.asc` | An OpenPGP signature over `SHA256SUMS.txt` |
|
||||
| `IMAGE-DIGEST.txt` | The container image of this version, pinned by digest |
|
||||
|
||||
Each tarball holds one top-level directory, `nxdns-<version>-<triple>/`, with six files in it: the `nxdns` binary at mode 0755, and `nxdns.service`, `nxdns.conf`, `LICENSE`, `THIRD-PARTY-NOTICES` and `INSTALL.md` at 0644.
|
||||
The signature covers `SHA256SUMS.txt`, and `SHA256SUMS.txt` covers everything else. Someone who can replace a tarball on its way to you can replace the checksum file next to it, but cannot sign it.
|
||||
|
||||
`SHA256SUMS.txt` covers `IMAGE-DIGEST.txt` rather than the image, because the image digest does not exist until the push has happened and cannot be computed by the build. Signing the file that names the digest gets you the same guarantee in one signature.
|
||||
|
||||
The `.txt` on three of the five names is not decoration. Gitea decides what an attachment may be by its file extension, and whether it accepts an extensionless upload at all is untested against this instance, so the release uses names it is known to accept. On disk, `zig build dist` still writes a file called `SHA256SUMS`; the release job copies it to `SHA256SUMS.txt` and appends the image line before signing.
|
||||
|
||||
## 1. Pick a version
|
||||
|
||||
Every URL below takes the version from one shell variable. Ask the server rather than typing a number that goes stale: Gitea redirects `releases/latest` to the tag page of the newest published release — newest by publication time, and drafts and pre-releases are excluded.
|
||||
|
||||
```sh
|
||||
BASE=https://git.mial.net/mokhtar/nxdns
|
||||
VERSION=$(curl -fsS -o /dev/null -w '%{redirect_url}' "$BASE/releases/latest" |
|
||||
sed 's#.*/releases/tag/v##')
|
||||
echo "$VERSION"
|
||||
```
|
||||
|
||||
To take a particular version instead, set it yourself — substitute the one you want for the placeholder:
|
||||
|
||||
```sh
|
||||
VERSION=<version>
|
||||
```
|
||||
|
||||
> Verified: the two-command form, run against this repository, printed `0.0.1`
|
||||
> with `v0.0.1` published.
|
||||
|
||||
Pin the version in anything you script or automate. `latest` is convenient for a person at a terminal and a liability in a machine that upgrades itself.
|
||||
|
||||
## 2. Download
|
||||
## 1. Download
|
||||
|
||||
```sh
|
||||
mkdir -p ~/nxdns-release && cd ~/nxdns-release
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/nxdns-$VERSION-x86_64-linux-musl.tar.gz"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/SHA256SUMS.txt.asc"
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/IMAGE-DIGEST.txt"
|
||||
BASE=https://git.mial.net/mokhtar/nxdns/releases/download/v<version>
|
||||
curl -fLO "$BASE/nxdns-<version>-x86_64-linux-musl.tar.gz"
|
||||
curl -fLO "$BASE/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/SHA256SUMS.txt.asc"
|
||||
curl -fLO "$BASE/IMAGE-DIGEST.txt"
|
||||
```
|
||||
|
||||
`-L` is not optional: Gitea answers an asset URL with a 303 to wherever the attachment is actually stored.
|
||||
Take the `aarch64` tarball instead for a Raspberry Pi.
|
||||
|
||||
For the aarch64 tarball, or for both, swap or add the filename:
|
||||
## 2. Import the signing key
|
||||
|
||||
```sh
|
||||
curl -fLO "$BASE/releases/download/v$VERSION/nxdns-$VERSION-aarch64-linux-musl.tar.gz"
|
||||
```
|
||||
|
||||
Gitea also accepts the literal word `latest` in place of the tag, so the three assets whose names carry no version can be fetched without one:
|
||||
|
||||
```sh
|
||||
curl -fLO "$BASE/releases/download/latest/SHA256SUMS.txt"
|
||||
curl -fLO "$BASE/releases/download/latest/SHA256SUMS.txt.asc"
|
||||
curl -fLO "$BASE/releases/download/latest/IMAGE-DIGEST.txt"
|
||||
```
|
||||
|
||||
That is the Gitea spelling, and it is not GitHub's. `releases/latest/download/` — the form GitHub uses — is a 404 on Gitea; the alias goes in the tag position, as `releases/download/latest/`. The tarball filenames contain the version, so this alias never saves you from knowing it for those two.
|
||||
|
||||
> Verified against `v0.0.1`: all five assets downloaded through the versioned
|
||||
> path, `SHA256SUMS.txt` downloaded again through the `latest` alias and hashed
|
||||
> identical, and GitHub's spelling answered 404.
|
||||
|
||||
## 3. Check the signature over `SHA256SUMS.txt`
|
||||
|
||||
Get the public key first. It is a signing subkey of the key that signs every commit in this repository, so you can confirm the fingerprint against a clone you already have with `git log --show-signature` or `git verify-tag v$VERSION`:
|
||||
Releases are signed by a subkey of this key:
|
||||
|
||||
```
|
||||
A2061F6AB24DF2C0E92346FD1509B54946D08A95
|
||||
@@ -96,18 +42,16 @@ curl -fsSL https://keys.openpgp.org/vks/v1/by-fingerprint/A2061F6AB24DF2C0E92346
|
||||
gpg --import
|
||||
```
|
||||
|
||||
> Verified: the key is published, and that exact `curl | gpg --import` reported
|
||||
> `key 1509B54946D08A95: public key "Mokhtar Mial (pc) <…>"
|
||||
> imported` into a clean `GNUPGHOME`.
|
||||
The same key signs every commit and tag in the repository, so `git verify-tag v<version>` in a clone confirms it independently.
|
||||
|
||||
Then verify:
|
||||
## 3. Check the signature
|
||||
|
||||
```sh
|
||||
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
|
||||
```
|
||||
|
||||
```
|
||||
gpg: Signature made Sun 09 Aug 2026 01:26:42 AM CEST
|
||||
gpg: Signature made <date and time of the release>
|
||||
gpg: using EDDSA key 019D00DF8417EBFDA5471E5EF7319CC024FB5A96
|
||||
gpg: Good signature from "Mokhtar Mial (pc) <…>" [unknown]
|
||||
gpg: WARNING: This key is not certified with a trusted signature!
|
||||
@@ -116,34 +60,14 @@ Primary key fingerprint: A206 1F6A B24D F2C0 E923 46FD 1509 B549 46D0 8A95
|
||||
Subkey fingerprint: 019D 00DF 8417 EBFD A547 1E5E F731 9CC0 24FB 5A96
|
||||
```
|
||||
|
||||
The *structure* is what to read: three lines, not one. `using EDDSA key` and `Subkey fingerprint` name the signing subkey that actually made the signature; `Primary key fingerprint` names the certificate it hangs off, and that is the one published above. The subkey fingerprint can change — a signing subkey is revoked and replaced on its own — but the primary fingerprint is the project's identity and stays.
|
||||
|
||||
Exit status 0, and `Good signature`. That warning is normal and is not a failure: it says you have not told GnuPG you believe the key belongs to the person it claims to.
|
||||
|
||||
Now compare the `Primary key fingerprint` line with the fingerprint in this page. GnuPG prints it as ten space-separated groups of four hex digits, with a double space in the middle, while the fingerprint above is the same 40 characters unspaced — so compare the hex digits in order and ignore the spacing, or strip it and let the shell do it:
|
||||
Two things must hold: the output says `Good signature`, and the `Primary key fingerprint` is the fingerprint in step 2. GnuPG prints it in groups of four; this prints it unspaced for comparison:
|
||||
|
||||
```sh
|
||||
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt 2>&1 |
|
||||
sed -n 's/^Primary key fingerprint: //p' | tr -d ' '
|
||||
```
|
||||
|
||||
That prints the 40-character form, ready to compare with `A2061F6AB24DF2C0E92346FD1509B54946D08A95`. Do not skip the comparison — `gpg --verify` exits 0 for a good signature from *any* key in your keyring, including one an attacker talked you into importing.
|
||||
|
||||
A tampered `SHA256SUMS.txt` looks like this, and exits 1:
|
||||
|
||||
```
|
||||
gpg: Signature made Sun 09 Aug 2026 01:26:42 AM CEST
|
||||
gpg: using EDDSA key 019D00DF8417EBFDA5471E5EF7319CC024FB5A96
|
||||
gpg: BAD signature from "Mokhtar Mial (pc) <…>" [unknown]
|
||||
```
|
||||
|
||||
> Verified against `v0.0.1`, from a clean `GNUPGHOME` holding only the imported
|
||||
> public key — which is why the `[unknown]` trust marker and the warning are
|
||||
> there rather than being written in by hand. The good-signature transcript is
|
||||
> the real release's; the `BAD signature` transcript is the same command
|
||||
> against a copy of `SHA256SUMS.txt` with one newline appended, and it exited
|
||||
> 1. The `sed`/`tr` pipeline printed
|
||||
> `A2061F6AB24DF2C0E92346FD1509B54946D08A95`, matching the fingerprint above.
|
||||
Do not skip the fingerprint. `gpg --verify` accepts a good signature from any key in your keyring. The `WARNING` lines are normal: they only mean you have not told GnuPG that you trust the key.
|
||||
|
||||
## 4. Check the hashes
|
||||
|
||||
@@ -156,135 +80,92 @@ nxdns-<version>-x86_64-linux-musl.tar.gz: OK
|
||||
IMAGE-DIGEST.txt: OK
|
||||
```
|
||||
|
||||
`--ignore-missing` is what makes this work when you downloaded one tarball out of the two. Without it, `sha256sum` treats every line it cannot read as a failure and exits 1:
|
||||
`--ignore-missing` skips the tarball you did not download. A file that does not match prints `FAILED` and `sha256sum` exits 1.
|
||||
|
||||
```
|
||||
nxdns-<version>-x86_64-linux-musl.tar.gz: OK
|
||||
sha256sum: nxdns-<version>-aarch64-linux-musl.tar.gz: No such file or directory
|
||||
nxdns-<version>-aarch64-linux-musl.tar.gz: FAILED open or read
|
||||
IMAGE-DIGEST.txt: OK
|
||||
sha256sum: WARNING: 1 listed file could not be read
|
||||
```
|
||||
|
||||
A file that is present but does not match is the case that matters, and it says `FAILED` with no `open or read`:
|
||||
|
||||
```
|
||||
nxdns-<version>-x86_64-linux-musl.tar.gz: FAILED
|
||||
IMAGE-DIGEST.txt: OK
|
||||
sha256sum: WARNING: 1 computed checksum did NOT match
|
||||
```
|
||||
|
||||
Check the signature before the hashes, not after. An attacker who can replace the tarball can replace `SHA256SUMS.txt` next to it; the signature is the only thing in the set they cannot forge.
|
||||
|
||||
> Verified against `v0.0.1`: with both tarballs present, `sha256sum -c` printed
|
||||
> three `OK` lines. The three transcripts above are the same command over
|
||||
> copies of the real assets, with the aarch64 tarball absent for the first two
|
||||
> and one byte appended to the x86_64 tarball for the third. Only the version
|
||||
> in the filenames was replaced with `<version>`.
|
||||
|
||||
## 5. Look inside before extracting
|
||||
## 5. Look inside the tarball
|
||||
|
||||
```sh
|
||||
tar -tvzf nxdns-$VERSION-x86_64-linux-musl.tar.gz
|
||||
tar -tvzf nxdns-<version>-x86_64-linux-musl.tar.gz
|
||||
```
|
||||
|
||||
Expect exactly one top-level directory and the six files listed above, with mode `-rwxr-xr-x` on `nxdns` and `-rw-r--r--` on the rest, no symlinks, and no path that begins with `/` or contains `..`. `zig build verify-dist` asserts all of that on the extracted archive before a release is ever published, so this is a second opinion rather than the only check — but it costs nothing and it is the step that catches a tarball that is not the one you think it is.
|
||||
```
|
||||
drwxr-xr-x 0/0 0 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl
|
||||
-rw-r--r-- 0/0 4229 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/INSTALL.md
|
||||
-rw-r--r-- 0/0 14210 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/LICENSE
|
||||
-rw-r--r-- 0/0 72967 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/THIRD-PARTY-NOTICES
|
||||
-rwxr-xr-x 0/0 7257952 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/nxdns
|
||||
-rw-r--r-- 0/0 31 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/nxdns.conf
|
||||
-rw-r--r-- 0/0 1547 1970-01-01 01:00 nxdns-<version>-x86_64-linux-musl/nxdns.service
|
||||
```
|
||||
|
||||
Then extract:
|
||||
Expect one directory and these six files, with no links and no path that starts with `/` or contains `..`. The sizes differ from release to release; the dates are always the epoch, shown in your time zone. Then:
|
||||
|
||||
```sh
|
||||
tar -xzf nxdns-$VERSION-x86_64-linux-musl.tar.gz
|
||||
./nxdns-$VERSION-x86_64-linux-musl/nxdns version
|
||||
tar -xzf nxdns-<version>-x86_64-linux-musl.tar.gz
|
||||
./nxdns-<version>-x86_64-linux-musl/nxdns version
|
||||
```
|
||||
|
||||
`version` prints the version, then the Zig version the binary was built with. The version has to match the tag you downloaded. The binary carries no commit sha, so the check that ties a release to its source is the rebuild below rather than a string in this output.
|
||||
|
||||
> Verified against `v0.0.1`: both tarballs listed exactly the one directory and
|
||||
> six files with the stated modes, no symlinks and no absolute or `..` paths,
|
||||
> and the extracted binary printed `nxdns 0.0.1` then `zig 0.16.0`.
|
||||
The first line it prints must be `nxdns <version>`, the version you downloaded.
|
||||
|
||||
## 6. Verify the container image
|
||||
|
||||
`IMAGE-DIGEST.txt` holds one line: the image reference this version pushed, pinned by the digest of its index, in the form
|
||||
`IMAGE-DIGEST.txt` names the image this version published, pinned by digest:
|
||||
|
||||
```
|
||||
git.mial.net/mokhtar/nxdns:<version>@sha256:<64 hex digits>
|
||||
```
|
||||
|
||||
`SHA256SUMS.txt` covers `IMAGE-DIGEST.txt`, so the signature you already checked covers that line too. Confirm the tag in the registry still resolves to that digest:
|
||||
|
||||
```sh
|
||||
cut -d@ -f2 IMAGE-DIGEST.txt
|
||||
docker buildx imagetools inspect git.mial.net/mokhtar/nxdns:$VERSION \
|
||||
--format '{{.Manifest.Digest}}'
|
||||
```
|
||||
|
||||
The two have to be the same string. A registry tag is mutable; the digest is not, so pull the whole pinned reference rather than the tag when you care:
|
||||
The signature you checked covers this line. A tag in a registry can be moved; a digest cannot. Pull the pinned reference:
|
||||
|
||||
```sh
|
||||
docker pull "$(cat IMAGE-DIGEST.txt)"
|
||||
```
|
||||
|
||||
The index should carry exactly two platforms and nothing else:
|
||||
Or check that the tag still points at it, comparing the two lines it prints:
|
||||
|
||||
```sh
|
||||
docker buildx imagetools inspect git.mial.net/mokhtar/nxdns:$VERSION \
|
||||
--format '{{range .Manifest.Manifests}}{{.Platform.OS}}/{{.Platform.Architecture}} {{end}}'
|
||||
cut -d@ -f2 IMAGE-DIGEST.txt
|
||||
docker buildx imagetools inspect git.mial.net/mokhtar/nxdns:<version> --format '{{.Manifest.Digest}}'
|
||||
```
|
||||
|
||||
`linux/amd64 linux/arm64`. The build passes `--provenance=false --sbom=false`, so there are no `unknown/unknown` attestation entries in the list; seeing any means the image did not come from this pipeline.
|
||||
|
||||
The binary inside the image is the same file as the one in the matching tarball, and the release checks that before publishing. To check it yourself:
|
||||
The image holds exactly `linux/amd64` and `linux/arm64`, and its binary is the same file as the one in the x86_64 tarball:
|
||||
|
||||
```sh
|
||||
docker create --name nxdns-verify git.mial.net/mokhtar/nxdns:$VERSION
|
||||
docker create --name nxdns-verify "$(cat IMAGE-DIGEST.txt)"
|
||||
docker cp nxdns-verify:/nxdns ./nxdns-from-image
|
||||
docker rm nxdns-verify
|
||||
sha256sum ./nxdns-from-image ./nxdns-$VERSION-x86_64-linux-musl/nxdns
|
||||
sha256sum ./nxdns-from-image ./nxdns-<version>-x86_64-linux-musl/nxdns
|
||||
```
|
||||
|
||||
> Verified against `v0.0.1`: the digest in `IMAGE-DIGEST.txt` and the digest
|
||||
> the `:0.0.1` tag resolves to were the same string
|
||||
> (`sha256:f2945fbf6c1e16509f0e33e3d62da9a9cd7dc706718d333ce4edf95c80dbb00e`,
|
||||
> and `:latest` resolved to it too), the platform form printed exactly
|
||||
> `linux/amd64 linux/arm64` with no attestation entries, `docker pull` of the
|
||||
> pinned reference succeeded, and the binary copied out of that pulled image
|
||||
> hashed identical to the `nxdns` in the x86_64 tarball.
|
||||
## If a check fails
|
||||
|
||||
## What the signature proves, and what it does not
|
||||
Do not run the binary.
|
||||
|
||||
It proves two things:
|
||||
- `sha256sum` says `FAILED` after a good signature: the download is damaged or was replaced. Delete it and download it again, over another network if you can.
|
||||
- `gpg` says `BAD signature`: `SHA256SUMS.txt` and its signature do not belong together. Download both again; a signature left over from another version is the usual cause.
|
||||
- `gpg` says `No public key`: import the key from step 2.
|
||||
- The fingerprint does not match step 2: take this one seriously. Do not extract the tarball, and do not import other keys to make it pass.
|
||||
|
||||
- The release was produced by this project's release pipeline, using a key only that pipeline holds.
|
||||
- What you have on disk is byte for byte what that pipeline uploaded. A corrupted download, a modified mirror or a tampered proxy all break the check.
|
||||
## What the signature does not prove
|
||||
|
||||
It does not prove that the binary in the tarball was built from the source in this repository. The machine that ran the build also held the signing key, so a compromise of that machine produces an artifact that is signed, verifies cleanly, and contains whatever the attacker put in it. The signature is a statement about origin and integrity in transit. It is not a statement about provenance from source.
|
||||
The signature proves the files came from the project's release pipeline and that you have the bytes it uploaded. It does not prove that the binary was built from the published source: the machine that built it also signed it.
|
||||
|
||||
Closing that gap needs a reproducible build — an independent build, run somewhere else, that lands on the same bytes. The release tarballs are reproducible: the binary carries no commit sha, the archive is written by the project's own tool with fixed modes, zero timestamps and sorted entries, and CI rebuilds the same bytes and compares them against the pinned hashes before it uploads anything. The rebuild below is how you check that for yourself.
|
||||
|
||||
The signing key is a subkey rather than the primary key, which limits the damage of the case above: a leaked release subkey is revoked on its own and the identity, the commit signatures and everyone's existing trust in the key survive.
|
||||
|
||||
## Rebuild it yourself
|
||||
|
||||
Build the same version from source and compare the hashes. Match the toolchain first: `ZIG_VERSION`, `NODE_VERSION` and `NPM_VERSION` at the top of `.gitea/workflows/gates.yml` are the exact versions the release used, and a different patch release of any of them changes the bytes.
|
||||
|
||||
Zig has to be the official ziglang.org tarball for that version, not your distribution's package of it. A distro package of `0.16.0` is built against the system LLVM and emits different machine code than the official build, and both print `0.16.0`, so the version string tells you nothing. This is not hypothetical: the first cut of `flake.nix` pinned hashes CI could not reproduce for exactly that reason, and the release cut now downloads the official tarball itself rather than trusting `PATH`. Fetch and verify it the same way, against the `ZIG_TARBALL_SHA256` pin that sits next to `ZIG_VERSION` in `gates.yml` (CI installs the same bytes through setup-zig, which checks them by minisign):
|
||||
The release builds are reproducible, so you can check that yourself by building the same version from source and comparing hashes. It takes the exact toolchain the release used, named at the top of `.gitea/workflows/gates.yml`: `ZIG_VERSION` with its `ZIG_TARBALL_SHA256`, `NODE_VERSION` and `NPM_VERSION`. Use the official Zig tarball from ziglang.org, not a distribution's package of the same version: a distribution build of Zig produces different machine code while printing the same version. The rebuild reproduces the release only on x86_64 Linux with glibc.
|
||||
|
||||
```sh
|
||||
git clone https://git.mial.net/mokhtar/nxdns
|
||||
cd nxdns
|
||||
git checkout "v$VERSION"
|
||||
git verify-tag "v$VERSION"
|
||||
git checkout v<version>
|
||||
git verify-tag v<version>
|
||||
|
||||
ZIG_VERSION=$(sed -n 's/^ ZIG_VERSION: "\(.*\)"$/\1/p' .gitea/workflows/gates.yml)
|
||||
ZIG_TARBALL_SHA256=$(sed -n 's/^ ZIG_TARBALL_SHA256: "\(.*\)"$/\1/p' .gitea/workflows/gates.yml)
|
||||
curl -fsSL -o ../zig.tar.xz "https://ziglang.org/download/$ZIG_VERSION/zig-x86_64-linux-$ZIG_VERSION.tar.xz"
|
||||
(cd .. && echo "$ZIG_TARBALL_SHA256 zig.tar.xz" | sha256sum -c - && tar -xJf zig.tar.xz)
|
||||
ZIG="$(cd .. && pwd)/zig-x86_64-linux-$ZIG_VERSION/zig"
|
||||
"$ZIG" version
|
||||
```
|
||||
|
||||
The host matters too: the admin bundle is built with host-native Rolldown and Lightning CSS bindings, which the lockfile ships per platform and libc, so the recipe reproduces the release only on x86_64 Linux with glibc, the runner CI uses. The two `npm_config_*` paths must not exist on your machine; the recipe relies on npm finding no config file there. The environment matters as much as the toolchain. The release cut and CI both build the bundle under exactly nine variables and a `022` umask, so the recipe below does the same: a locale, a time zone, a build timestamp or a file mode picked up from your shell each move the bytes. The Zig build gets a private `--cache-dir` so a stale local cache cannot leak into them; the global Zig cache stays shared, because it is content-addressed and a fresh one refetches every dependency (see `specs/release-cut.md`).
|
||||
Then build in a clean environment. A locale, a time zone or a umask picked up from your shell changes the output, and the two `npm_config_*` paths must not exist:
|
||||
|
||||
```sh
|
||||
env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global \
|
||||
@@ -292,37 +173,11 @@ env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=t
|
||||
|
||||
env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global \
|
||||
sh -c 'umask 022 && exec "'"$ZIG"'" build dist \
|
||||
-Dversion-string="'"$VERSION"'" \
|
||||
-Dversion-string=<version> \
|
||||
-Dadmin-dist=admin/dist -Doptimize=ReleaseSafe \
|
||||
--cache-dir "$(mktemp -d)"'
|
||||
|
||||
sha256sum zig-out/dist/nxdns-"$VERSION"-*.tar.gz
|
||||
sha256sum zig-out/dist/nxdns-<version>-*.tar.gz
|
||||
```
|
||||
|
||||
`git verify-tag` is the check that the tag itself is signed by the key from step 3, and it is the one part of this section that stands on its own: it ties the source you just checked out to the same identity that signed the release.
|
||||
|
||||
`zig build dist` writes `zig-out/dist/`: the two tarballs, a staging directory per target under `stage/`, the stripped binaries under `bin/<triple>/`, and a `SHA256SUMS` covering the two tarballs. The published `SHA256SUMS.txt` is that file with a third line for `IMAGE-DIGEST.txt` appended by the release job, so the two tarball lines should match and the local file has no third line to compare.
|
||||
|
||||
The tarball is written by `zig build dist` itself rather than by the host's `tar` and `gzip`, so its layout is fixed and a rebuild on a matching toolchain reproduces it byte for byte. Entries are sorted by their full path as bytes, with the payload directory first. The payload directory and `nxdns` carry mode `0755`; every other file carries `0644`. Every entry has a zero modification time, uid 0, gid 0, and no user or group name. The gzip wrapper carries no original filename and a zero header timestamp, which is what makes two archives of the same tree compare equal.
|
||||
|
||||
Compare your two tarball hashes against two things: the published `SHA256SUMS.txt`, and the `hashes` block of `flake.nix` at the tag, which carries the same digests in SRI form. All three agree on a matching toolchain, and the release pipeline fails before it uploads anything if they do not.
|
||||
|
||||
A hash that differs is a signal to check the toolchain and the environment first. A distribution's Zig package instead of the official tarball is the first thing to rule out; an unpinned Node or npm version is the next ordinary explanation, and a build run outside the normalized environment above is the next one. Rule both out before you conclude anything about the release itself.
|
||||
|
||||
> Verified on 2026-10-19 against `v0.0.21`, on x86_64 Linux with glibc, Node 24.19.0 and npm 11.17.0: from a fresh clone, `git verify-tag v0.0.21` printed `Good signature`, the freshly downloaded Zig tarball passed its `sha256sum -c`, and both rebuilt tarball hashes matched the published `SHA256SUMS.txt` and the `flake.nix` pins at the tag (`26615c4b…b3b4ce` for x86_64, `29746c9a…7f19af` for aarch64). The two `sh -c` wrappers were replaced by the same nine-variable `env -i` and a `022` umask set in the calling shell. The host was the maintainer's own machine, in a fresh directory with a private `--cache-dir`, so this run shows the recipe works; it is not a third-party reproduction. An earlier run against `v0.0.1`, before the build was reproducible, did not match.
|
||||
|
||||
## If a check fails
|
||||
|
||||
Stop and do not run the binary.
|
||||
|
||||
- `sha256sum` says `FAILED` but the signature was good — you have a damaged or substituted download. Delete it and fetch it again over a different network before assuming anything worse.
|
||||
- `gpg` says `BAD signature` — `SHA256SUMS.txt` and `SHA256SUMS.txt.asc` do not belong together. Re-download both from the release page; a stale `SHA256SUMS.txt.asc` left over from a previous version is the boring explanation.
|
||||
- `gpg` says `Can't check signature: No public key` — you have not imported the key, or you imported a different one.
|
||||
- The fingerprint does not match the one in step 3 — that is the case to take seriously. Do not extract the tarball, and do not import more keys trying to make it pass.
|
||||
|
||||
## Related
|
||||
|
||||
- [Install with systemd](install-with-systemd.md) — where the verified tarball goes next.
|
||||
- [Install with Docker](install-with-docker.md) — the published image.
|
||||
- [Upgrade nxdns](upgrade.md) — the same verification, on the way to a newer version.
|
||||
- [Performance targets and what the tests prove](../explanation/performance-and-testing.md) — the other place this project writes down what its checks do not cover.
|
||||
Both hashes must match the tarball lines of the published `SHA256SUMS.txt`. If they do not, check the toolchain and the environment first: a distribution's Zig, a different Node or npm, or a build outside `env -i` are the usual causes.
|
||||
|
||||
Reference in New Issue
Block a user