milestone 11: systemd and docker packaging, operator and architecture docs, config and api reference, docs drift guards

2026-08-02 15:24:10 +02:00
parent a589df7515
commit bdb6ffab7a
29 changed files with 1936 additions and 94 deletions
@@ -0,0 +1,169 @@
+# nxdns REST API
+
+nxdns serves its admin API itself, on `web.bind:web.port` (default port 8080),
+as plain HTTP. TLS termination, where an operator wants it, belongs to a
+reverse proxy in front; the session cookie deliberately omits the `Secure`
+attribute so the supported plain-HTTP LAN deployment works.
+
+This page is orientation. The machine-readable contract is
+`src/web/openapi.yaml`, which the running server hands out unauthenticated at
+`GET /api/openapi.yaml`. When this page and the yaml disagree, the yaml wins.
+
+## Conventions
+
+- All request and response bodies are JSON (`application/json`), except
+  `/metrics` (Prometheus text format), `/api/openapi.yaml` (YAML) and
+  `/api/queries/live` (`text/event-stream`).
+- Field names are snake_case, matching settings keys and SQL column names.
+- Every error response carries the envelope `{"error": "<message>"}`. The
+  message is operator-facing text; internal detail never reaches the wire —
+  a 500 body is generic and the cause goes to the server log.
+- Request bodies are strict: an unknown field is a 400, a body over 1 MiB is
+  a 413.
+- A request whose path matches but whose method does not answers 405 with an
+  `Allow` header. An unknown `/api` path is a JSON 404; unknown non-`/api`
+  paths fall through to the embedded SPA (`index.html`), so client-side
+  routing works.
+- Item routes (`{id}`) match a positive integer id only.
+- Mutations to groups, blocklists, rules, local records, forward zones,
+  clients and client prefixes take effect live. Upstreams and `/api/settings`
+  are restart-required.
+
+## Authentication
+
+Cookie sessions, in memory, no accounts — one operator password.
+
+- Authentication is on exactly when `web.password_hash` is set. When no
+  password is set, every route is open and `POST /api/auth/login` answers
+  `{"authenticated": true, "auth_required": false}` without setting a cookie.
+- `POST /api/auth/login` takes `{"password": "..."}`. A correct password
+  answers 200 with a `Set-Cookie` for `nxdns_session`
+  (`HttpOnly; SameSite=Lax; Path=/`, `Max-Age` = the session TTL). A wrong
+  password is a 401; a stored hash the server cannot read is a 500, never a
+  401. Login attempts spend rate-limit tokens like any other request, and
+  argon2id verification is deliberately slow.
+- Every route whose auth policy is `session` answers
+  401 `{"error": "authentication required"}` without a valid cookie.
+- Sessions live `web.session_ttl_hours` (default 24) from login; use does not
+  extend the lifetime. The table holds 32 sessions; a 33rd login evicts the
+  least recently used. Nothing is persisted — a server restart logs every
+  operator out.
+- Changing the password through `PUT /api/settings` revokes every live
+  session immediately; the new password applies without a restart.
+- `POST /api/auth/logout` ends the cookie's session and clears the cookie.
+  It answers 200 whether or not the session was live.
+
+## Rate limiting
+
+A token bucket per client address: capacity and refill are both
+`web.api_rate_limit_per_min` (default 300) per minute, so a page-load burst
+up to the capacity is admitted and the long-run rate holds.
+
+- An over-budget request answers 429 `{"error": "rate limited"}` with a
+  `Retry-After` header giving the seconds until a token is available
+  (rounded up, never zero).
+- Loopback addresses (127.0.0.0/8 and ::1) are exempt while
+  `web.api_localhost_exempt` is true (the default).
+- Exempt routes, which never consult a bucket: `/metrics` and `/api/health`
+  (a Prometheus scrape must never see 429) and `/api/queries/live` (one
+  long-lived stream must not drain its address's bucket; it is bounded by
+  the SSE connection cap instead).
+- The limiter tracks at most 4096 addresses. When the table is full and no
+  slot is reclaimable, requests from unknown addresses are refused with 429.
+
+## Live query stream (SSE)
+
+`GET /api/queries/live` is server-sent events over chunked transfer,
+`Content-Type: text/event-stream`, `Cache-Control: no-store`.
+
+- The stream opens with `retry: 3000`, so a browser `EventSource` reconnects
+  on its own after a drop.
+- Each query is one frame: `event: query` and a single `data:` line of JSON.
+  The payload carries the `GET /api/queries` row fields minus `id` (a live
+  entry precedes persistence): `ts`, `domain`, `client_ip`, `qtype`,
+  `blocked`, `block_reason`, `response_time_us`, `cache_hit`, `upstream`.
+- A `: ping` comment heartbeat goes out after 15 s of quiet, keeping
+  middleboxes from reaping the idle connection.
+- Each subscriber buffers up to 64 entries. A client too slow for the query
+  rate overflows its buffer and the server ends the stream cleanly after
+  delivering what the buffer held — queries are never held back for a slow
+  reader. There is no gap marker: on reconnect, re-sync through
+  `GET /api/queries`, which has the missed rows.
+- Connections per client address are capped at
+  `web.sse_max_connections_per_ip` (default 3); over the cap is a 429. The
+  cap binds loopback too. The server holds at most 32 concurrent streams in
+  total; when all slots are taken, the answer is a 503.
+
+## Operations
+
+Auth `open` means no session required; `session` means a valid session
+cookie is required whenever a password is set. Rate limit `counted` spends a
+token; `exempt` never consults the limiter.
+
+| Method | Path | Auth | Rate limit | Purpose |
+|---|---|---|---|---|
+| GET | `/metrics` | open | exempt | Prometheus metrics |
+| GET | `/api/health` | open | exempt | Health rollup |
+| GET | `/api/version` | open | counted | Build and uptime |
+| GET | `/api/openapi.yaml` | open | counted | This API's OpenAPI document |
+| POST | `/api/auth/login` | open | counted | Log in |
+| POST | `/api/auth/logout` | session | counted | Log out |
+| GET | `/api/queries` | session | counted | Query log page |
+| GET | `/api/queries/live` | session | exempt | Live query stream (server-sent events) |
+| GET | `/api/stats` | session | counted | Totals for a period |
+| GET | `/api/stats/timeseries` | session | counted | Bucketed counts for a period |
+| GET | `/api/lookup` | session | counted | Explain a domain |
+| GET | `/api/upstream/health` | session | counted | Upstream pool health |
+| GET | `/api/groups` | session | counted | List groups |
+| POST | `/api/groups` | session | counted | Create a group |
+| GET | `/api/groups/{id}` | session | counted | Read a group |
+| PUT | `/api/groups/{id}` | session | counted | Update a group |
+| DELETE | `/api/groups/{id}` | session | counted | Delete a group |
+| GET | `/api/groups/{id}/sources` | session | counted | Blocklist sources assigned to a group |
+| PUT | `/api/groups/{id}/sources` | session | counted | Replace the assignment |
+| GET | `/api/blocklists` | session | counted | List blocklist sources |
+| POST | `/api/blocklists` | session | counted | Add a blocklist source |
+| POST | `/api/blocklists/update` | session | counted | Refresh every enabled source now |
+| GET | `/api/blocklists/{id}` | session | counted | Read a blocklist source |
+| PUT | `/api/blocklists/{id}` | session | counted | Update a blocklist source |
+| DELETE | `/api/blocklists/{id}` | session | counted | Delete a blocklist source |
+| GET | `/api/rules` | session | counted | List rules |
+| POST | `/api/rules` | session | counted | Create a rule |
+| GET | `/api/rules/{id}` | session | counted | Read a rule |
+| PUT | `/api/rules/{id}` | session | counted | Update a rule |
+| DELETE | `/api/rules/{id}` | session | counted | Delete a rule |
+| GET | `/api/local-records` | session | counted | List local DNS records |
+| POST | `/api/local-records` | session | counted | Create a local record |
+| GET | `/api/local-records/{id}` | session | counted | Read a local record |
+| PUT | `/api/local-records/{id}` | session | counted | Update a local record |
+| DELETE | `/api/local-records/{id}` | session | counted | Delete a local record |
+| GET | `/api/forward-zones` | session | counted | List forward zones |
+| POST | `/api/forward-zones` | session | counted | Create a forward zone |
+| GET | `/api/forward-zones/{id}` | session | counted | Read a forward zone |
+| PUT | `/api/forward-zones/{id}` | session | counted | Update a forward zone |
+| DELETE | `/api/forward-zones/{id}` | session | counted | Delete a forward zone |
+| GET | `/api/clients` | session | counted | List clients |
+| GET | `/api/clients/{id}` | session | counted | Read a client |
+| PUT | `/api/clients/{id}` | session | counted | Rename or regroup a client |
+| DELETE | `/api/clients/{id}` | session | counted | Forget a client |
+| GET | `/api/client-prefixes` | session | counted | List client prefixes |
+| PUT | `/api/client-prefixes` | session | counted | Replace the prefix table |
+| GET | `/api/upstreams` | session | counted | List upstream resolvers |
+| POST | `/api/upstreams` | session | counted | Add an upstream |
+| GET | `/api/upstreams/{id}` | session | counted | Read an upstream |
+| PUT | `/api/upstreams/{id}` | session | counted | Update an upstream |
+| DELETE | `/api/upstreams/{id}` | session | counted | Delete an upstream |
+| GET | `/api/pause` | session | counted | Read the pause state |
+| POST | `/api/pause` | session | counted | Pause or resume blocking |
+| GET | `/api/settings` | session | counted | Read the scalar settings |
+| PUT | `/api/settings` | session | counted | Update settings |
+| POST | `/api/certs/reload` | session | counted | Reload the TLS certificates from disk |
+
+There is no `POST /api/clients`: client rows come from DNS activity or
+import, never from the API.
+
+## Schemas
+
+Request and response schemas for every operation live in the OpenAPI
+document: `src/web/openapi.yaml` in the repository, or
+`GET /api/openapi.yaml` from a running server.
@@ -0,0 +1,182 @@
+# Architecture
+
+nxdns is a self-hosted DNS sinkhole for a household LAN: one static Zig binary
+that answers DNS on UDP/TCP 53 (optionally DoH and DoT), filters against
+blocklists, and serves an embedded admin SPA over HTTP. This document is a map
+of the source tree and the few design rules that hold everywhere.
+
+## Module map
+
+Top-level files:
+
+| File | Role |
+|---|---|
+| `src/main.zig` | Process shell: writers, argv, dispatch, exit code. |
+| `src/cli.zig` | Every command body (`run`, `check`, `export`, `import`, `version`, `help`); takes its writers as parameters so tests capture output without a process. |
+| `src/app.zig` | The composition root: everything `nxdns run` owns, built in order. Nothing else constructs a collaborator. |
+| `src/version.zig` | Build-time version strings. |
+| `src/tests.zig` | Test root; imports each file directly. |
+
+Directories:
+
+| Directory | Role |
+|---|---|
+| `src/dns/` | Pure DNS wire format: header, names, questions, records, whole packets, EDNS(0)/ECS (`edns.zig`), enums and limits (`types.zig`). No allocation, no `std.Io` beyond writing to a caller's writer. |
+| `src/filter/` | Blocklist pipeline: line parsers (hosts, domains, ABP), the compiler that turns a downloaded list into `.list`/`.wild` bodies, `domain_set.zig` (exact-match set, no Bloom filter), `matcher.zig` (the immutable snapshot every query evaluates against), per-group `rules.zig`, `wildcard.zig`, `safesearch.zig`, blocked-response synthesis (`response.zig`). Two I/O edges live here too: `fetcher.zig` (HTTP download) and `manager.zig` (files + DB + snapshot swap). |
+| `src/local/` | Local DNS records and conditional forward zones: immutable lookup tables built once from DB rows (`records.zig`, `forward_zones.zig`), plus the plain UDP/TCP client for LAN resolvers (`forward_client.zig`). |
+| `src/cache/` | `dns_cache.zig`: bounded in-memory TTL cache of whole response messages, keyed by the question. The clock arrives as a parameter. |
+| `src/upstream/` | Upstream resolution: shared vocabulary and the `Client` interface (`transport.zig`), DoH client (RFC 8484), DoT client (RFC 7858), per-endpoint health/backoff (`health.zig`), and `pool.zig` — priority-ordered sequential failover that is itself a `transport.Client`, so the handler sees one interface. |
+| `src/server/` | The serving side: UDP/TCP/DoH/DoT listeners, `handler.zig` (the whole query pipeline), `cert_store.zig` (refcounted TLS cert holder), `rate_limiter.zig`, `pause.zig`, `clients.zig` (client auto-materialisation), `local_tables.zig` (published local-answer tables), `query_sink.zig` (log/SSE fanout), `shutdown.zig` (SIGINT/SIGTERM → one `std.Io.Event`). |
+| `src/storage/` | SQLite ownership: `db.zig` is the only file that calls SQLite, `config_schema.zig` + `migrations.zig` for `config.db`, `querylog_schema.zig` (open-or-recreate), async query `logger.zig`, `retention.zig`, `disk_monitor.zig`, and one repository per table under `repositories/`. |
+| `src/config/` | The one configuration model (`model.zig`), the pure validator (`validate.zig`), `import.zig`/`export.zig` (ZON ⇄ `config.db`, byte-stable round trip), `bootstrap.zig` (first-start seeding — a policy wrapper over import). |
+| `src/web/` | The admin HTTP layer: `server.zig` (listener), `router.zig`/`routes.zig`, one file per resource under `handlers/`, `auth.zig` (sessions), `sse.zig` (live query fanout), `static.zig` (embedded SPA), `metrics.zig` (Prometheus), `openapi.zig` (served contract), `api_limiter.zig`, `http_util.zig`. |
+| `src/platform/` | OS and TLS edges: IP address values, the `std.log` sink (`logging.zig`), `statfs.zig` (free-space query via libc), client TLS over `std.crypto.tls` (`tls_client.zig`), server TLS over vendored Mbed TLS (`tls_server.zig`). |
+
+The SPA source lives in `web/` at the repo root; the build embeds its `dist/`
+output as the `web_assets` module (`-Dweb-dist`).
+
+```
+main.zig ── cli.zig ── app.zig (composition root)
+                          │ injects std.Io + collaborators
+   ┌──────────────────────┴───────────────────────┐
+   │  server/    web/    upstream/    storage/    │  I/O edge
+   │  platform/  config/{import,export,bootstrap} │
+   ├──────────────────────────────────────────────┤
+   │  dns/   filter/*   local/*   cache/          │  pure core:
+   │  config/{model,validate}                     │  bytes in, bytes out
+   └──────────────────────────────────────────────┘
+   * except filter/{fetcher,manager}.zig and local/forward_client.zig,
+     which are those directories' named I/O edges
+```
+
+## The purity rule
+
+`dns/`, `filter/`, `local/` and `cache/` take bytes and return bytes: no
+`std.Io`, no sockets, no clocks hidden inside (AGENTS.md). Anything that needs
+a timestamp takes it as a parameter — the cache, the rate limiter and the
+pause flag all work this way, so every decision is testable without a backend.
+The exceptions are deliberate and few: `filter/fetcher.zig` downloads lists,
+`filter/manager.zig` owns the compiled files, the DB columns and the snapshot
+swap, and `local/forward_client.zig` speaks UDP/TCP to a LAN resolver. The
+decision path a query takes through these directories allocates nothing and
+opens nothing.
+
+## std.Io injection
+
+There is one `std.Io` in the process. `main` receives it through
+`std.process.Init` — on the standard start path this is the Threaded backend
+(`std.Io.Threaded`, constructed in the stdlib's start code) — and hands it to
+`cli.Runner`, from which `app.zig` threads it into every collaborator as a
+parameter. No module constructs its own event loop or reads an ambient clock;
+tests build their own `std.Io.Threaded` instance and pass it the same way.
+The one deliberate exception is `storage/db.zig`: SQLite performs its own file
+I/O through its VFS, so that file takes no `std.Io` at all.
+
+## Life of one query
+
+The pipeline in `src/server/handler.zig` (its order is PLAN §4; the stages
+below are the code's actual call chain — `Handler.handle` then `Context.run`):
+
+```
+UDP/53  TCP/53  DoH  DoT          (src/server/{udp,tcp,doh,dot}_server.zig)
+   └──────┴──────┴────┘
+          │ raw query bytes, listener-owned buffers
+          ▼
+  handler.handle
+     ├─ header parse (too short / QR set → counted drop)
+     ├─ rate limit (over budget → REFUSED)
+     ├─ packet + EDNS validation (FORMERR / NOTIMP)
+     ├─ client tracking, group lookup (snapshot.groupForClient)
+     │
+     ├─ local records ────────────────► authoritative answer
+     ├─ forward zones ─► cache ─► LAN resolver ─► answer
+     │
+     └─ upstream path
+          ├─ filter snapshot evaluate ─► blocked? synthesized block reply
+          ├─ safe-search rewrite (per group)
+          ├─ cache get ─► hit? answer
+          ├─ upstream pool: priority failover across DoH/DoT endpoints
+          ├─ CNAME uncloak: walk the answer's chain, re-evaluate each target
+          └─ cache put
+          ▼
+  reply bytes ─► listener sends
+          │
+          └─► QuerySink ─► SSE hub (GET /api/queries/live)
+                        └─► async logger ─► querylog.db
+```
+
+Local records win over forward zones, and both win over filtering: a name
+nxdns answers itself never reaches a blocklist. Pause suspends filtering only;
+local records, forward zones, cache, upstream and the query log keep running.
+`handle` returns no error union — every failure is either a DNS response the
+client can act on or a counted drop. The query path never waits on the
+database: `QuerySink` copies the entry, the SSE hub gets it first, and one
+writer task owns the `querylog.db` handle behind an `std.Io.Queue`.
+
+## Storage
+
+Two databases with opposite contracts:
+
+- **`config.db` is the truth.** Schema DDL is carried verbatim by
+  `migrations.zig` as step 1; a schema change is a new migration step, applied
+  inside one transaction. `nxdns import` replaces its whole content atomically
+  (`BEGIN IMMEDIATE`; a failed import changes nothing), `nxdns export` renders
+  it back as canonical ZON, byte-identical across round trips. A config file
+  seeds the DB exactly once at first start (`config/bootstrap.zig`); the DB is
+  truth thereafter.
+- **`querylog.db` is expendable.** It is never migrated: its schema carries a
+  fingerprint derived from the DDL text, and a mismatch at open replaces the
+  file (`storage/querylog_schema.zig`). Retention deletes old rows daily and
+  periodically rewrites the file; `config.db` is walled off from that churn.
+
+## Web stack
+
+`web/server.zig` runs one `std.http.Server` per connection over its own accept
+loop, with fixed pre-allocated connection slots, optionally behind TLS. The
+SPA is embedded at build time: `static.zig` serves the `web_assets` module —
+bytes, content type, strong ETag, and a pre-compressed `.gz` sibling where it
+paid off — via a linear scan, no filesystem at runtime. `GET /api/queries/live`
+is server-sent events over chunked transfer, fed by the same `QuerySink` the
+logger reads. Routing is a flat table (`routes.zig`) matched linearly; the
+OpenAPI YAML is hand-written, embedded and served at `GET /api/openapi.yaml`,
+kept honest by tests that assert every served route appears in it.
+
+Auth (`web/auth.zig`): the operator's password is verified against an argon2id
+PHC string (`web.password_hash` — the plaintext is hashed on import and never
+stored). A successful login mints a 256-bit token carried in a cookie; the
+in-memory session table holds only SHA-256 digests of tokens, compared in
+constant time, capped at 32 sessions with LRU eviction. Nothing is persisted —
+a restart logs everyone out. Monitoring endpoints (health, version, metrics),
+the served OpenAPI contract and login itself are unauthenticated; everything
+else requires the cookie, and
+the API has its own token-bucket rate limiter.
+
+## DoH, DoT and certificate hot-reload
+
+`server/doh_server.zig` (RFC 8484 over HTTP/1.1 + TLS) and
+`server/dot_server.zig` (RFC 7858) mirror the plain listeners' shape. Server
+TLS terminates in Mbed TLS (`platform/tls_server.zig`), exposing plaintext as
+`std.Io.Reader`/`std.Io.Writer`.
+
+Certificates hot-reload through `server/cert_store.zig`: one refcounted
+`CertStore` per endpoint owns the published TLS context generation; listeners
+`acquire` it per connection and `release` it when the connection ends, so a
+reload never frees a context mid-handshake. Reload publishes nothing on
+failure — both PEM files are read and a whole new context built before
+anything swaps, and any failure leaves the old generation serving. A watcher
+polls mtime+size of both files every 30 s; `POST /api/certs/reload` triggers
+the same path on demand and reports the per-endpoint outcome as its payload.
+
+## Failure visibility
+
+Every failure mode must be visible, and the surface is counters, not log
+lines (AGENTS.md). The handler counts every outcome — drops, FORMERR,
+SERVFAIL, blocked, truncated, cache hits, paused and unfiltered queries — in
+atomics; listeners count dropped datagrams instead of queueing them
+unboundedly. `GET /metrics` renders all of it as Prometheus text 0.0.4, and
+`GET /api/health` rolls it up for a monitor (always 200: "degraded" is a fact
+about the box, not a failed request). The disk monitor classifies free space
+against thresholds and gates non-essential writes; the query logger holds its
+batches while writes are disallowed. `std.log` is reserved for failures
+nobody else records, with upstream-error deduplication so a flapping resolver
+cannot fill a disk.
@@ -0,0 +1,451 @@
+# Configuration reference
+
+Every section, field and collection nxdns accepts, with its type, default,
+unit, validation rule and the subsystem that consumes it. Source of truth:
+`src/config/model.zig` (the model and defaults), `src/config/validate.zig`
+(the rules), `src/config/{bootstrap,import,export}.zig` (the lifecycle).
+
+## How configuration works
+
+The database is the truth; the file is a seed.
+
+- On `nxdns run`, the configuration file (default `/etc/nxdns/config.zon`,
+  overridable with `--config`) is imported into `config.db` **once**: only
+  when the file exists and the database has never been configured. On every
+  later start the file is ignored and the database is used as it is
+  (`src/config/bootstrap.zig`). A file that exists but is unreadable,
+  unparseable or invalid fails the start — nxdns never falls back to silent
+  defaults over a file the operator wrote.
+- After the seed, changes are made through the web API (or `nxdns import
+  --force`), never by editing the file. Editing the file after first boot has
+  no effect.
+- `nxdns export` renders the database back as canonical ZON: fixed two-line
+  header, every default emitted, deterministic ordering, no timestamps. The
+  round trip `export` → `import` → `export` is byte-identical. With `--out
+  FILE` the write is atomic and the file is created mode 0600, because the
+  export carries `web.password_hash`.
+- `nxdns import FILE` replaces the whole database content in one transaction.
+  Without `--force` it refuses a database that already has content
+  (`error.DatabaseNotEmpty`); a failed import leaves the database untouched.
+- `nxdns check` validates without writing. Source selection order: an
+  explicit `--config FILE` wins; otherwise `config.db` in the data directory
+  if it exists; otherwise the default config file path if it exists;
+  otherwise "nothing to check" (exit 2). `check` also verifies TLS
+  certificate/key readability and, from the command line, probes each enabled
+  upstream with a real query.
+
+Absent fields keep their defaults — in the file and in the database. A
+settings key stored in the database that the running binary does not know is
+warned about and ignored, never an error, so a downgrade cannot brick a
+config database.
+
+## What is not in the file
+
+Storage paths are process arguments, not configuration:
+
+- `--data-dir DIR` (default `/var/lib/nxdns`) holds `config.db` and
+  `querylog.db`. The directory is created mode 0700; both databases and their
+  WAL sidecars are forced to mode 0600.
+- `--config FILE` (default `/etc/nxdns/config.zon`) names the seed file.
+- `--web-dev DIR` (`run` only) serves the web interface from a directory
+  instead of the embedded assets.
+
+## File format
+
+The file is ZON: a top-level anonymous struct whose fields are the sections
+and collections below. Enum values are written as ZON enum literals
+(`.level = .err`, `.response = .nxdomain`). Strings are double-quoted. The
+file may be at most 4 MiB (`ConfigTooLarge` beyond that). A syntax error is
+reported with its line and column.
+
+One serialization quirk: the log level `error` is the Zig keyword `error`,
+so the ZON/model tag is `.err` while the database stores the operator-facing
+word `"error"`. `err` is not accepted as database text, and `error` is not a
+ZON tag — the file says `.err`, the settings API says `"error"`.
+
+## Scalar sections
+
+The "Key" column is the settings key as stored in the database
+(`section.field`); in the file the same field lives inside its section block,
+e.g. `.dns = .{ .port = 53 }`.
+
+### upstream
+
+Timeouts for talking to upstream resolvers.
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `upstream.read_timeout_ms` | u32 | 3000 | ms | 100–120000 | read deadline on conditional-forward-zone exchanges (`src/server/handler.zig` via `app.zig`) |
+| `upstream.total_timeout_ms` | u32 | 5000 | ms | 100–120000, and at least `read_timeout_ms` | per-query budget of the upstream pool (`src/upstream/pool.zig`) — the whole attempt including the connect; also the `nxdns check` probe deadline |
+
+### dns
+
+The plain DNS listener (UDP + TCP).
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `dns.bind_ipv4` | string | `"0.0.0.0"` | IP address | must parse as an IPv4 address | UDP/TCP listener bind (`src/app.zig`) |
+| `dns.bind_ipv6` | string | `"::"` | IP address | must parse as an IPv6 address | UDP/TCP listener bind (`src/app.zig`) |
+| `dns.port` | u16 | 53 | port | 1–65535 | UDP/TCP listener port |
+| `dns.rate_limit` | u32 | 1000 | queries per window | at least 1 | per-client DNS rate limiter (`src/server/rate_limiter.zig`) |
+| `dns.rate_window_seconds` | u32 | 60 | seconds | 1–3600 | window of the same limiter |
+
+### blocking
+
+What a blocked query gets back.
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `blocking.response` | enum `.zero` \| `.nxdomain` | `.zero` | — | one of the two tags | blocked-response synthesis (`src/filter/response.zig`): `.zero` answers 0.0.0.0 / `::`, `.nxdomain` answers NXDOMAIN |
+| `blocking.ttl` | u32 | 5 | seconds | at most 86400 (0 allowed) | TTL on the synthesized block answer |
+
+### cache
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `cache.size` | u32 | 10000 | entries | none; `0` disables caching (put short-circuits — `src/cache/dns_cache.zig` test "a cache of zero entries stores nothing") | DNS answer cache capacity (`src/cache/dns_cache.zig`) |
+| `cache.negative_ttl_max` | u32 | 3600 | seconds | at most 86400 | cap on cached negative answers; 0 disables negative caching |
+
+### web
+
+The web interface and REST API.
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `web.enabled` | bool | true | — | — | gates the whole web stack: server, sessions, SSE hub, API limiter (`src/app.zig`) |
+| `web.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | web listener bind (`src/web/server.zig`) |
+| `web.port` | u16 | 8080 | port | 1–65535 | web listener port |
+| `web.password` | string | `""` | — | must not be set together with `web.password_hash` | operator input only — see "Authentication" below; never stored, never a settings key |
+| `web.password_hash` | string | `""` | — | — | argon2id PHC string verified at login (`src/web/auth.zig`); `""` disables authentication |
+| `web.session_ttl_hours` | u16 | 24 | hours | at least 1 | session expiry and cookie Max-Age (`src/web/auth.zig`) |
+| `web.api_rate_limit_per_min` | u32 | 300 | requests per minute | at least 1 | API token-bucket limiter (`src/web/api_limiter.zig`) |
+| `web.api_localhost_exempt` | bool | true | — | — | loopback requests skip the API limiter |
+| `web.sse_max_connections_per_ip` | u16 | 3 | connections | at least 1 | cap on concurrent SSE streams per client IP |
+
+### doh_server
+
+The DNS-over-HTTPS listener (server side, for clients on the LAN).
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `doh_server.enabled` | bool | false | — | — | gates the DoH listener (`src/server/doh_server.zig`) |
+| `doh_server.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | DoH listener bind |
+| `doh_server.port` | u16 | 443 | port | 1–65535 | DoH listener port |
+| `doh_server.cert_path` | string | `"/etc/nxdns/cert.pem"` | path | non-empty when enabled | certificate loaded into the hot-reloading `CertStore`; readability is checked by `nxdns check`, not the validator |
+| `doh_server.key_path` | string | `"/etc/nxdns/key.pem"` | path | non-empty when enabled | private key for the same; `nxdns check` warns when it is readable beyond its owner |
+
+### dot_server
+
+The DNS-over-TLS listener. Same shape as `doh_server`; only the default port
+differs.
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `dot_server.enabled` | bool | false | — | — | gates the DoT listener (`src/server/dot_server.zig`) |
+| `dot_server.bind` | string | `"0.0.0.0"` | IP address | must parse as an IP address | DoT listener bind |
+| `dot_server.port` | u16 | 853 | port | 1–65535 | DoT listener port |
+| `dot_server.cert_path` | string | `"/etc/nxdns/cert.pem"` | path | non-empty when enabled | certificate, shared `CertStore` with hot reload |
+| `dot_server.key_path` | string | `"/etc/nxdns/key.pem"` | path | non-empty when enabled | private key for the same |
+
+### edns
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `edns.ecs_mode` | enum `.strip` \| `.forward` | `.strip` | — | one of the two tags | EDNS Client Subnet handling in the query path (`src/server/handler.zig`, `src/dns/edns.zig`): `.strip` removes the client subnet before forwarding, `.forward` passes it through |
+
+### logging
+
+Process log and query log behavior.
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `logging.level` | enum `.err` \| `.warn` \| `.info` \| `.debug` | `.info` | — | one of the four tags; stored as `"error"`/`"warn"`/`"info"`/`"debug"` | log threshold (`src/platform/logging.zig`) |
+| `logging.retention_days` | u16 | 30 | days | at least 1 | query-log pruning cutoff (`src/storage/retention.zig`) and the client tracker's last-seen cutoff (`src/server/clients.zig`) |
+| `logging.query_log_buffer_max` | u32 | 10000 | entries | at least 1 | in-memory query-log ring size and backpressure cap (`src/storage/logger.zig`) |
+| `logging.hide_domains` | bool | false | — | — | query log stores a hidden marker instead of the domain |
+| `logging.hide_client_ips` | bool | false | — | — | query log stores a hidden marker instead of the client IP |
+| `logging.output` | enum `.stderr` \| `.syslog` \| `.file` | `.stderr` | — | one of the three tags | log sink selection (`src/platform/logging.zig`); `.stderr` and `.syslog` both write to stderr (journald captures it), `.file` rotates |
+| `logging.file_path` | string | `"/var/log/nxdns/nxdns.log"` | path | when `output` is `.file`: non-empty absolute path | rotating log file; its directory also feeds the disk monitor. The binary does not create the directory |
+| `logging.max_size_mb` | u32 | 50 | MiB | at least 1 | rotation trigger for the log file |
+| `logging.max_files` | u8 | 5 | files | at least 1 | rotated generations kept |
+
+### disk
+
+Free-space thresholds for the data directory. When free space falls below
+them, the query-log writer, client tracker and blocklist scheduler are
+throttled (`src/storage/disk_monitor.zig`).
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `disk.min_free_mb` | u32 | 200 | MiB | at least 1, and not above `warn_free_mb` | `critical` threshold |
+| `disk.warn_free_mb` | u32 | 500 | MiB | at least 1 | `warn` threshold |
+
+### blocklist_update
+
+| Key | Type | Default | Unit | Validation | Consumed by |
+|---|---|---|---|---|---|
+| `blocklist_update.enabled` | bool | true | — | — | blocklist refresh scheduler (`src/filter/manager.zig`); when false only the startup pass runs |
+| `blocklist_update.interval_hours` | u16 | 24 | hours | at least 1 | sleep between refresh passes and the per-source staleness test |
+
+## Collections
+
+Collections are ZON lists of structs. Fields without a default are required.
+Runtime columns (first/last seen timestamps, per-source download counters)
+are deliberately not part of the model: import sets timestamps to the import
+time, and export omits them, which is what keeps the round trip byte-stable.
+
+### groups
+
+Client groups. A group named `default` is **required**; every client not
+assigned elsewhere lands in it, and import guarantees it keeps database id 1.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `name` | string | required | non-empty, unique |
+| `safe_search` | bool | false | — |
+
+Consumed by the filter engine (`src/filter/matcher.zig`); `safe_search`
+triggers the safe-search rewrite in the query path.
+
+### upstreams
+
+Upstream resolvers. **At least one enabled upstream is required.**
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `url` | string | required | `https://` (DoH) or `tls://` (DoT) endpoint; unique |
+| `priority` | i32 | 100 | — (lower is tried first) |
+| `enabled` | bool | true | — |
+| `tls_name` | string | `""` | DoT only — a `tls_name` on an `https://` upstream is an error; must be a valid domain name |
+
+Consumed by the upstream pool (`src/upstream/pool.zig`): entries are sorted
+by ascending priority and tried in order with failover. `tls_name` sets SNI
+and the certificate verification name for a `tls://` upstream written as an
+IP literal; empty means "verify by the URL host"
+(`src/upstream/dot_client.zig`).
+
+### clients
+
+Known clients with a fixed group assignment.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `ip` | string | required | IP address; unique after canonicalization (`FD00::1` and `fd00:0:0:0:0:0:0:1` collide) |
+| `name` | string | `""` | — (display only, never read by the resolver) |
+| `group` | string | `"default"` | must name a declared group |
+
+Consumed by the filter engine's exact IP → group lookup
+(`src/filter/matcher.zig`).
+
+### client_prefixes
+
+Group assignment by CIDR prefix, for clients without an exact entry.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `prefix` | string | required | CIDR prefix (`192.168.2.0/24`, `fd00:abcd::/48`); unique after canonicalization |
+| `group` | string | `"default"` | must name a declared group |
+| `priority` | i32 | 100 | — (ties on match are broken by lower priority) |
+
+Consumed by the filter engine's longest-prefix match
+(`src/filter/matcher.zig`).
+
+### blocklist_sources
+
+Downloadable blocklists.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `url` | string | required | `http://` or `https://` URL with a host; unique |
+| `name` | string | required | non-empty |
+| `enabled` | bool | true | — |
+| `is_suggested` | bool | false | — (web UI hint only, never read by the resolver) |
+
+Consumed by the blocklist manager (`src/filter/manager.zig`): downloaded by
+the fetcher, compiled into domain sets; a disabled source is neither
+downloaded nor loaded.
+
+### group_sources
+
+Which groups consult which blocklist sources.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `group` | string | required | must name a declared group |
+| `source_url` | string | required | must name a declared blocklist source's `url`; the (group, source_url) pair is unique |
+
+Consumed by the filter engine when assembling each group's compiled domain
+sets (`src/filter/matcher.zig`). A link to a disabled source is silently
+skipped.
+
+### rules
+
+Per-group allow/block overrides, checked before the blocklists.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `group` | string | required | must name a declared group |
+| `pattern` | string | required | see below |
+| `kind` | enum `.exact` \| `.wildcard` | required | — |
+| `action` | enum `.allow` \| `.block` | required | — |
+
+Pattern rules: an `.exact` pattern is a plain domain name and may not contain
+`*`; a `.wildcard` pattern must contain at least one label that is exactly
+`*` (`*.tracker.example`, or `*` alone), and every other label must be a
+legal DNS label. `ads*.example` is not a valid wildcard.
+
+Consumed by the filter engine's rule sets (`src/filter/rules.zig`).
+
+### local_records
+
+Local DNS answers, served without touching any upstream.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `name` | string | required | valid domain name |
+| `rtype` | enum `.a` \| `.aaaa` \| `.cname` | required | stored as `A`/`AAAA`/`CNAME` |
+| `value` | string | required | IPv4 address for `.a`, IPv6 for `.aaaa`, domain name for `.cname` |
+| `ttl` | u32 | 300 | 1–604800 seconds |
+
+The (name, rtype, value) triple is unique. Consumed by the local records
+table in the query path (`src/local/records.zig`).
+
+### forward_zones
+
+Zones resolved by a specific resolver instead of the configured upstreams —
+for LAN or corporate domains.
+
+| Field | Type | Default | Validation |
+|---|---|---|---|
+| `zone` | string | required | valid domain name; unique |
+| `resolver` | string | required | `udp://IP:port` or `tcp://IP:port`; the host must be an IP literal and the port is mandatory |
+
+The resolver host must be an IP literal because resolving the resolver's own
+name would be a bootstrap problem. Matching is longest suffix
+(`src/local/forward_zones.zig`); the exchange is UDP-then-TCP
+(`src/local/forward_client.zig`) with `upstream.read_timeout_ms` as the read
+deadline.
+
+## Authentication: web.password vs web.password_hash
+
+Exactly one of the two may be set; setting both is refused
+(`PasswordAndHashBothSet` — ambiguity in a security setting).
+
+- `web.password` is operator input only. At import time it is hashed with
+  argon2id (OWASP parameters: t=2, m=19 MiB, p=1, PHC encoding) into
+  `web.password_hash` and discarded. It is never stored — there is no
+  `web.password` settings row, and `nxdns export` always writes
+  `.password = ""`.
+- `web.password_hash` is the stored argon2id PHC string. Supplying it
+  directly (for example from a previous export) is how a backup restores
+  authentication without knowing the password.
+- Both empty disables web authentication entirely.
+
+Because the export carries the hash and re-importing an exported file takes
+the "password is empty" branch, the export/import round trip preserves the
+hash byte-for-byte.
+
+## Minimal working example
+
+The smallest file that passes validation: a `default` group and one enabled
+upstream. Everything else keeps its default.
+
+```zon
+.{
+    .groups = .{ .{ .name = "default" } },
+    .upstreams = .{ .{ .url = "https://dns.quad9.net/dns-query" } },
+}
+```
+
+## Fuller annotated example
+
+```zon
+.{
+    // Plain DNS on the standard port, rate-limited per client.
+    .dns = .{
+        .bind_ipv4 = "0.0.0.0",
+        .bind_ipv6 = "::",
+        .port = 53,
+        .rate_limit = 1000,
+        .rate_window_seconds = 60,
+    },
+
+    // Blocked queries answer 0.0.0.0 / :: with a 5 second TTL.
+    .blocking = .{ .response = .zero, .ttl = 5 },
+
+    .cache = .{ .size = 10000, .negative_ttl_max = 3600 },
+
+    // Web UI on 8080. The password is hashed at import and never stored;
+    // leave .password_hash out when setting .password (they are exclusive).
+    .web = .{
+        .enabled = true,
+        .port = 8080,
+        .password = "correct horse battery staple",
+        .session_ttl_hours = 24,
+    },
+
+    // Serve DoT to the LAN. The key file should be mode 0600.
+    .dot_server = .{
+        .enabled = true,
+        .port = 853,
+        .cert_path = "/etc/nxdns/cert.pem",
+        .key_path = "/etc/nxdns/key.pem",
+    },
+
+    // Strip EDNS Client Subnet before forwarding (the default).
+    .edns = .{ .ecs_mode = .strip },
+
+    // ".err" in the file; the settings API shows it as "error".
+    .logging = .{ .level = .err, .retention_days = 14 },
+
+    .blocklist_update = .{ .enabled = true, .interval_hours = 24 },
+
+    // "default" is mandatory. Additional groups get their own rules,
+    // blocklists and safe-search flag.
+    .groups = .{
+        .{ .name = "default" },
+        .{ .name = "kids", .safe_search = true },
+    },
+
+    // Lower priority is tried first; the second entry is a failover.
+    // tls_name is needed when a tls:// upstream is written as an IP
+    // literal, so certificate verification has a DNS name to match.
+    .upstreams = .{
+        .{ .url = "https://dns.quad9.net/dns-query", .priority = 10 },
+        .{ .url = "tls://9.9.9.9:853", .priority = 20, .tls_name = "dns.quad9.net" },
+    },
+
+    // Exact client assignments win over prefixes.
+    .clients = .{
+        .{ .ip = "192.168.1.20", .name = "tablet", .group = "kids" },
+    },
+    .client_prefixes = .{
+        .{ .prefix = "192.168.2.0/24", .group = "kids" },
+    },
+
+    .blocklist_sources = .{
+        .{ .url = "https://lists.example/ads.txt", .name = "ads" },
+    },
+    .group_sources = .{
+        .{ .group = "kids", .source_url = "https://lists.example/ads.txt" },
+    },
+
+    // Overrides beat blocklists. Wildcards need a label that is exactly "*".
+    .rules = .{
+        .{ .group = "default", .pattern = "allowed.example", .kind = .exact, .action = .allow },
+        .{ .group = "kids", .pattern = "*.tracker.example", .kind = .wildcard, .action = .block },
+    },
+
+    // Local names, answered without any upstream.
+    .local_records = .{
+        .{ .name = "nas.lan", .rtype = .a, .value = "192.168.1.5" },
+        .{ .name = "www.lan", .rtype = .cname, .value = "nas.lan" },
+    },
+
+    // Everything under corp.lan goes to the LAN resolver directly.
+    .forward_zones = .{
+        .{ .zone = "corp.lan", .resolver = "udp://192.168.1.1:53" },
+    },
+}
+```
+
@@ -0,0 +1,7 @@
+//! Embeds the documentation files the drift tests guard. Module root for the
+//! `docs_files` anonymous import (test builds only) — @embedFile paths resolve
+//! relative to this file.
+
+pub const api_md = @embedFile("api.md");
+pub const config_reference_md = @embedFile("config-reference.md");
+pub const operator_md = @embedFile("operator.md");
@@ -0,0 +1,418 @@
+# Operating nxdns
+
+How to install, configure, back up, upgrade and troubleshoot an nxdns server.
+For the meaning of every configuration field, see
+[config-reference.md](config-reference.md); for the HTTP API,
+[api.md](api.md).
+
+## Install: systemd
+
+nxdns ships as one static musl binary. Build it (see
+[Building](#building-the-binary)) or take it from CI, then:
+
+```sh
+# 1. The binary.
+install -m 0755 nxdns /usr/local/bin/nxdns
+
+# 2. The service user. Static, not DynamicUser: the TLS key for DoH/DoT
+#    must be chown-able to a stable uid.
+install -m 0644 deploy/systemd/sysusers.conf /usr/lib/sysusers.d/nxdns.conf
+systemd-sysusers
+
+# 3. The unit.
+install -m 0644 deploy/systemd/nxdns.service /etc/systemd/system/nxdns.service
+systemctl daemon-reload
+```
+
+Do not create directories by hand. The unit's `StateDirectory=nxdns`,
+`LogsDirectory=nxdns` and `ConfigurationDirectory=nxdns` make systemd create
+`/var/lib/nxdns` (mode 0700, owned by `nxdns`), `/var/log/nxdns` and
+`/etc/nxdns` on first start.
+
+Write a seed configuration to `/etc/nxdns/config.zon`. The minimum that
+starts is one group named `default` and one enabled upstream:
+
+```zon
+.{
+    .groups = .{ .{ .name = "default" } },
+    .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } },
+    .web = .{ .password = "choose-a-real-password" },
+}
+```
+
+Then:
+
+```sh
+systemctl enable --now nxdns
+journalctl -u nxdns -f
+```
+
+nxdns logs to stderr by default and systemd captures that into the journal;
+nothing else needs configuring for logs. Port 53 needs
+`CAP_NET_BIND_SERVICE`, which the unit grants via `AmbientCapabilities`.
+
+If port 53 is already taken, see
+[Port 53 conflicts](#port-53-is-taken-systemd-resolved).
+
+### Building the binary
+
+Requires Zig 0.16.0 and Node.js 24 (for the web UI). From the repository
+root:
+
+```sh
+(cd web && npm ci && npm run build)
+zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
+```
+
+This produces static binaries for both deploy targets:
+
+- `zig-out/cross/x86_64-linux-musl/nxdns`
+- `zig-out/cross/aarch64-linux-musl/nxdns`
+
+### Raspberry Pi 5 recipe
+
+The Pi 5 is aarch64. Build on any machine (the cross build needs no
+toolchain beyond Zig itself), copy the binary over, then follow the systemd
+steps above on the Pi:
+
+```sh
+(cd web && npm ci && npm run build)
+zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
+scp zig-out/cross/aarch64-linux-musl/nxdns pi:/tmp/nxdns
+scp deploy/systemd/nxdns.service deploy/systemd/sysusers.conf pi:/tmp/
+
+# on the Pi, as root:
+install -m 0755 /tmp/nxdns /usr/local/bin/nxdns
+install -m 0644 /tmp/sysusers.conf /usr/lib/sysusers.d/nxdns.conf
+systemd-sysusers
+install -m 0644 /tmp/nxdns.service /etc/systemd/system/nxdns.service
+systemctl daemon-reload
+# write /etc/nxdns/config.zon, then:
+systemctl enable --now nxdns
+```
+
+The binary is statically linked against musl; it has no runtime
+dependencies on the Pi.
+
+## Install: Docker
+
+The image is built from a binary you compile first; the Dockerfile only
+assembles the filesystem. From the repository root:
+
+```sh
+(cd web && npm ci && npm run build)
+zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
+docker build -t nxdns -f deploy/docker/Dockerfile .
+```
+
+or, with compose (which runs the same build with the repository root as
+context):
+
+```sh
+cd deploy/docker
+docker compose build
+```
+
+The Dockerfile maps buildx's `TARGETARCH` onto the cross-target directory,
+so `docker buildx build --platform linux/arm64` produces the aarch64 image
+from the same `zig-out/cross` tree.
+
+Before the first `docker compose up`, create the seed configuration the
+compose file bind-mounts read-only at `/etc/nxdns`:
+
+```sh
+cd deploy/docker
+mkdir -p etc-nxdns
+$EDITOR etc-nxdns/config.zon   # the same minimal seed as the systemd path
+```
+
+The seed must be readable by uid 65532, the fixed container user; the bind
+mount is read-only, so the container cannot adjust permissions itself.
+World-readable (0644) is fine when the seed carries no secret; if it holds
+`web.password` or `web.password_hash` (a restored export), restrict it instead:
+`chown 65532:65532 etc-nxdns/config.zon && chmod 0600 etc-nxdns/config.zon`.
+
+Without a valid seed — at least a `default` group and one enabled
+upstream — the container exits with code 2, because a fresh volume holds an
+empty database and an empty database has no upstream to forward to.
+
+The compose file publishes 53/udp, 53/tcp and 8080, keeps the data in a
+named volume mounted at `/var/lib/nxdns`, and sets the per-network-namespace
+sysctl `net.ipv4.ip_unprivileged_port_start=0` so the nonroot user
+(uid 65532) can bind port 53. Uncomment the 443/853 port mappings when you
+enable the DoH or DoT listener.
+
+Do not point the host's `/etc/resolv.conf` at the nxdns container. The
+container resolves its upstream DoH/DoT hostnames through the host's DNS
+configuration; pointing that at nxdns itself makes the container's own
+lookups depend on the service they are trying to start.
+
+### Publishing the image to a private registry
+
+There is deliberately no registry push in CI — credentials and registry
+choice are an infrastructure decision, not this repository's. To publish
+manually, log in to your registry, tag the local image with the registry's
+name, and push: `docker login <registry>`, then
+`docker tag nxdns <registry>/<owner>/nxdns:<tag>`, then
+`docker push <registry>/<owner>/nxdns:<tag>`. The same works for a
+self-hosted Gitea registry such as git.mial.net.
+
+## First boot and configuration semantics
+
+The ZON file at `/etc/nxdns/config.zon` (or `--config`) seeds the database
+exactly once:
+
+- **No file:** normal steady state; the database is used as it is.
+- **File present, database empty:** the file is imported. A file that is
+  unreadable, unparseable or invalid is an error (exit 2, every problem
+  printed) — nxdns never falls back to silent defaults over a file you
+  wrote.
+- **File present, database already configured:** the file is ignored. The
+  database is the truth from the first successful seed onward.
+
+After the first boot, editing `config.zon` changes nothing. Change the
+configuration through the web UI, the REST API, or the export→edit→import
+cycle:
+
+```sh
+nxdns export --out config-backup.zon
+$EDITOR config-backup.zon
+systemctl stop nxdns
+nxdns import config-backup.zon --force
+systemctl start nxdns
+```
+
+`import` without `--force` refuses a database that already has content
+(exit 2), so a plain `import` can never clobber a configured server by
+accident.
+
+## Authentication setup
+
+Set `web.password` in the seed file (or in a file you `import`). At import
+time it is hashed with argon2id into `web.password_hash` and discarded; the
+plaintext is never stored anywhere. `nxdns export` always writes
+`.password = ""` and carries the hash instead, so an exported file
+re-imports without knowing the password. Setting both `password` and
+`password_hash` in one file is an error (exit 2). To change the password,
+export, set `.password` to the new value, clear `.password_hash` to `""`,
+and import with `--force`.
+
+## TLS for the DoH/DoT listeners
+
+Both listeners are disabled by default. To enable one, set
+`doh_server.enabled` / `dot_server.enabled` and point `cert_path` and
+`key_path` at a PEM certificate chain and key, conventionally under
+`/etc/nxdns`. Ownership depends on how you deploy.
+
+Under systemd, the service runs as the `nxdns` user:
+
+```sh
+chown nxdns:nxdns /etc/nxdns/cert.pem /etc/nxdns/key.pem
+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, so the container cannot fix
+permissions itself — the host-side files must already be readable by that
+uid. It has no name on the host or in the scratch image, so chown it
+numerically:
+
+```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
+```
+
+The key must be readable by the user nxdns runs as and only by its owner:
+`nxdns check` prints a WARN for a key with any group or other permission
+bits, and a FAIL (exit 2) for a cert or key the user cannot read. A
+certificate that fails to load at boot while its listener is enabled exits 2.
+
+Renewals need no restart. A watcher polls both files every 30 seconds and
+swaps the new pair in atomically; in-flight connections finish on the old
+certificate. To pick up a renewal immediately — for example from a certbot
+deploy hook — call `POST /api/certs/reload` (session-authenticated; see
+[api.md](api.md)). A reload that fails to parse leaves the old certificate
+serving and reports the error.
+
+## Backup, restore and upgrades
+
+**Backup** is one command against a stopped or running server:
+
+```sh
+nxdns export --out /some/backup/nxdns-config.zon
+```
+
+The write is atomic (temp file + rename) and mode 0600, because the file
+carries `web.password_hash` — treat backups as secrets. Without `--out` the
+export goes to stdout, where file permissions are your redirect's problem.
+The query log is deliberately not part of the backup; it is expendable
+history.
+
+**Restore** onto a fresh data directory or over an existing one:
+
+```sh
+nxdns import /some/backup/nxdns-config.zon --force
+```
+
+**Upgrades:** install the new binary, restart the service. Schema
+migrations run automatically at startup (and before `check`, `export` and
+`import`), so a database one schema version behind is upgraded in place.
+There is no downgrade path; take an export before upgrading.
+
+## Data directory layout
+
+Everything lives under the data directory (default `/var/lib/nxdns`,
+override with `--data-dir`), mode 0700:
+
+| Path | What it is |
+| --- | --- |
+| `config.db` (+ `-wal`, `-shm`) | The configuration database — the single source of truth, including `web.password_hash`. Mode 0600. Back it up via `nxdns export`. |
+| `querylog.db` (+ `-wal`, `-shm`) | The query log. Mode 0600 — it records every domain every client asked for. Expendable: if it is missing or unusable it is recreated empty. |
+| `blocklists/` | Compiled blocklist snapshots, two files per source: `<id>.list` (exact domains) and `<id>.wild` (wildcards). `.raw.tmp` / `.list.tmp` / `.wild.tmp` files are transient refresh state. |
+
+## CLI reference
+
+```
+nxdns <command> [options]
+```
+
+Flags take both spellings: `--flag value` and `--flag=value`.
+
+### `run`
+
+Serves DNS until SIGINT or SIGTERM.
+
+| Flag | Meaning |
+| --- | --- |
+| `--data-dir DIR` | Data directory (default `/var/lib/nxdns`). Created at 0700 if missing. |
+| `--config FILE` | Seed configuration file (default `/etc/nxdns/config.zon`). Read only when the database is empty. |
+| `--web-dev DIR` | Serve the web interface from DIR instead of the embedded assets, with no cache headers. Development only. |
+
+### `check`
+
+Validates the configuration and probes the upstreams. Exit 0 when clean,
+2 when it found problems, and it always reports every problem, not just the
+first. What it checks, in order:
+
+1. Which source to check (see [source selection](#check-source-selection)).
+2. Full validation — the same rules `import` enforces.
+3. For each enabled DoH/DoT listener: cert and key are readable (FAIL if
+   not), key permissions are owner-only (WARN if not).
+4. A live probe: one real A query for `example.com` through every enabled
+   upstream, using the same failover machinery the server uses. A FAIL line
+   names the upstream and the concrete cause. This probe leaves the machine,
+   so `check` needs network access to pass.
+
+| Flag | Meaning |
+| --- | --- |
+| `--data-dir DIR` | Data directory to look for `config.db` in. |
+| `--config FILE` | Check this file instead of the database. |
+
+#### check source selection
+
+- `--config FILE` given explicitly: check that file, nothing else.
+- Otherwise, if `<data-dir>/config.db` exists: check the database — the
+  right default, since the database is the truth on a configured server.
+- Otherwise, if the default config file exists: check it.
+- Otherwise: "nothing to check", exit 2.
+
+The first line of output always names which source was checked.
+
+### `export`
+
+Writes the configuration as ZON to stdout, or atomically at mode 0600 to
+`--out FILE`. `--out` paths are relative to the shell's working directory.
+
+| Flag | Meaning |
+| --- | --- |
+| `--data-dir DIR` | Data directory holding `config.db`. |
+| `--out FILE` | Write to FILE instead of stdout. |
+
+### `import FILE`
+
+Validates FILE and replaces the configuration with it. Prints every
+validation problem on failure. Refuses a non-empty database without
+`--force`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--data-dir DIR` | Data directory holding `config.db` (created if missing). |
+| `--force` | Replace a database that already has content. |
+
+### `version`
+
+Prints the nxdns version, git commit and Zig version.
+
+### `help`
+
+Prints usage. `--help` and `-h` do the same.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 1 | Runtime failure — I/O, database, out of memory. |
+| 2 | A configuration problem the operator can fix, or a `check` that found one. |
+| 64 | Usage error — unknown command or flag, missing argument. |
+
+## Troubleshooting
+
+### The service exits with code 2
+
+Exit 2 always means a configuration you can fix; `nxdns run` prints the
+cause and suggests `nxdns check`, which shows the full list. The usual
+causes:
+
+- Empty database and no seed file, or a seed file with no `default` group
+  or no enabled upstream. On a fresh install this means `config.zon` is
+  missing, in the wrong place, or invalid.
+- A seed or imported file that fails validation — every problem is printed
+  with its field name.
+- `dns.bind_ipv4` / `dns.bind_ipv6` is not an IP address, or a rate limit
+  is zero (possible only in a hand-edited database; `import` refuses both).
+- A DoH/DoT listener is enabled but its certificate or key is unreadable or
+  unparseable at boot.
+- `import` into a non-empty database without `--force`.
+
+### Port 53 is taken (systemd-resolved)
+
+On most systemd distributions, `systemd-resolved` owns a stub listener on
+`127.0.0.53:53`, and on some setups binds `0.0.0.0:53`. Turn the stub off
+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 the stub
+(`/run/systemd/resolve/stub-resolv.conf`), repoint it at
+`/run/systemd/resolve/resolv.conf` so the host still resolves. Do not point
+the host running nxdns at nxdns itself if that host is where nxdns resolves
+its upstream DoH/DoT hostnames — that is a bootstrap cycle.
+
+### Disk is filling up
+
+The disk monitor samples free space and database sizes once a minute and
+classifies the state against `disk.warn_free_mb` and `disk.min_free_mb`.
+Below the warn threshold it logs the transition; below `min_free_mb` it
+gates every non-essential write: the query logger holds its batches, the
+client tracker stops persisting, and the blocklist scheduler skips its
+refresh passes. DNS keeps answering throughout — resolution never degrades
+because the disk is full. The state and the size gauges are visible on
+`/metrics` and in the web UI. Recover space (lower
+`logging.retention_days`, or delete `querylog.db` with the service
+stopped) and writes resume on the next sample.
+
+### Blocklists are not filtering
+
+Serving starts even when no blocklist snapshot loads — a household loses
+more from DNS that refuses to start than from a window of unfiltered
+answers. The startup journal line says either `blocklist generation N` or
+`unfiltered (no blocklist snapshot)`. If it says unfiltered, check the
+journal for the download or compile warning that preceded it.