milestone 11: systemd and docker packaging, operator and architecture docs, config and api reference, docs drift guards
This commit is contained in:
@@ -136,3 +136,83 @@ jobs:
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
docker:
|
||||
runs-on: ubuntu-24.04
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Zig
|
||||
uses: mlugg/setup-zig@v2
|
||||
with:
|
||||
version: ${{ env.ZIG_VERSION }}
|
||||
|
||||
- name: Set up Node
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
|
||||
- name: Build the web UI
|
||||
working-directory: web
|
||||
run: |
|
||||
npm ci
|
||||
npm run build
|
||||
|
||||
- name: Build static musl executables
|
||||
run: zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
|
||||
|
||||
- name: Build the image
|
||||
run: docker build -t nxdns:ci -f deploy/docker/Dockerfile .
|
||||
|
||||
- name: Smoke test the container
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
docker run --rm nxdns:ci version
|
||||
|
||||
mkdir -p etc-nxdns
|
||||
cat > etc-nxdns/config.zon <<'EOF'
|
||||
.{
|
||||
.groups = .{ .{ .name = "default" } },
|
||||
.upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } },
|
||||
}
|
||||
EOF
|
||||
|
||||
cid=$(docker run -d --name nxdns-smoke \
|
||||
-p 127.0.0.1:8080:8080 \
|
||||
-v "$PWD/etc-nxdns:/etc/nxdns:ro" \
|
||||
nxdns:ci)
|
||||
trap 'docker rm -f nxdns-smoke >/dev/null 2>&1 || true' EXIT
|
||||
|
||||
# The published port works when the job runs on the docker host or in
|
||||
# DinD; the container IP covers a runner that shares the daemon over
|
||||
# a mounted socket.
|
||||
ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$cid")
|
||||
healthy=""
|
||||
for _ in $(seq 1 30); do
|
||||
if [ "$(docker inspect -f '{{.State.Running}}' "$cid")" != "true" ]; then
|
||||
echo "container exited during startup"
|
||||
docker logs "$cid" || true
|
||||
exit 1
|
||||
fi
|
||||
if curl -fsS "http://127.0.0.1:8080/api/health" \
|
||||
|| { [ -n "$ip" ] && curl -fsS "http://$ip:8080/api/health"; }; then
|
||||
healthy=1
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
if [ -z "$healthy" ]; then
|
||||
echo "no /api/health response within 30 seconds"
|
||||
docker logs "$cid" || true
|
||||
exit 1
|
||||
fi
|
||||
|
||||
docker stop -t 30 nxdns-smoke
|
||||
exit_code=$(docker inspect -f '{{.State.ExitCode}}' nxdns-smoke)
|
||||
echo "exit code after SIGTERM: $exit_code"
|
||||
docker logs nxdns-smoke || true
|
||||
test "$exit_code" -eq 0
|
||||
|
||||
@@ -54,7 +54,7 @@ Serves a household LAN (≈2–20 devices). Portfolio-grade public repo with ext
|
||||
Zig 0.16 stdlib is built on the `std.Io` interface: `std.Io.net` owns networking (`std.net` in its old form is gone) and `std.http.Client` requires an `io: Io`. Therefore:
|
||||
|
||||
- **`Io` is the injected platform abstraction.** Every component that does I/O takes `io: Io`. No project-owned wrapper interfaces around it — a second abstraction over an abstraction with one consumer is waste.
|
||||
- **Backend: `std.Io.Threaded` by default** — the mature, debuggable path; at ≤20 devices throughput is a non-issue. `std.Io.Evented` (io_uring) is selectable via config flag; the code is backend-agnostic by construction, so this is a switch, not a refactor.
|
||||
- **Backend: `std.Io.Threaded`** — the mature, debuggable path; at ≤20 devices throughput is a non-issue. The originally planned io_uring config flag was dropped in milestone 11: `std.Io.Evented` at Zig 0.16.0 stubs the networking a server needs — listen, accept, connect, lookup, and stream reads/writes return `error.NetworkDown` (`Uring.zig` netListenIp/netAccept/netConnectIp/netRead/netWrite) — so a selectable backend would boot a dead server. The code stays backend-agnostic by construction; revisit when std ships working evented networking.
|
||||
- No hand-written thread pool. `Io` async/concurrent/Group covers task management.
|
||||
- Core domain modules (`dns`, `filter`, `cache`) stay pure: no `Io`, no sockets — bytes in, bytes out. Only servers, upstream clients, and storage touch `Io`.
|
||||
|
||||
@@ -476,7 +476,6 @@ Periodic delete of rows older than `retention_days`; scheduled checkpoint/VACUUM
|
||||
.{
|
||||
.upstream = .{
|
||||
.servers = .{ "https://cloudflare-dns.com/dns-query", "tls://dns.google:853" },
|
||||
.connect_timeout_ms = 2000,
|
||||
.read_timeout_ms = 3000,
|
||||
},
|
||||
.dns = .{
|
||||
@@ -683,7 +682,7 @@ Exit: documented deployment works end-to-end on the Pi 5.
|
||||
| B | Rule kinds: exact, parent-walk, wildcard. Regex permanently out of scope |
|
||||
| C | In scope: local DoH/DoT server, local records, conditional forwarding. Out: HTTP/2, DoQ, DHCP, DNSSEC, clustering |
|
||||
| D | mbedTLS (vendored) terminates server TLS; stdlib TLS for upstream client |
|
||||
| E | `std.Io` injected everywhere; `Threaded` default backend, io_uring via flag; no custom thread pool |
|
||||
| E | `std.Io` injected everywhere; `Threaded` backend (io_uring flag dropped in m11 — Evented networking is stubbed at 0.16.0); no custom thread pool |
|
||||
| F | Config format: ZON via `std.zon`; DB is truth; export/import for backup + host moves |
|
||||
| G | SQLite vendored amalgamation + own thin wrapper |
|
||||
| H | Two DBs: `config.db` (precious) + `querylog.db` (expendable, self-contained, client IP as text) |
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# nxdns
|
||||
|
||||
A self-hosted DNS sinkhole for a household LAN, written in Zig 0.16. One
|
||||
static musl binary, SQLite for state, a Raspberry Pi 5 as the reference
|
||||
target. It answers your network's DNS, blocks what you tell it to, and shows
|
||||
you what asked for what.
|
||||
|
||||
## Features
|
||||
|
||||
- Blocklist filtering: subscribe to hosts/domain lists, plus your own allow
|
||||
and block rules with wildcard support (`*.example.com`)
|
||||
- Per-client policy groups: different filtering for the kids' tablet and
|
||||
your workstation
|
||||
- Local DNS records and conditional forwarding for internal zones
|
||||
- Encrypted upstreams: DNS-over-HTTPS and DNS-over-TLS with failover
|
||||
- Built-in DoH and DoT server endpoints, with certificate hot-reload
|
||||
- Bounded in-memory DNS cache with TTL-respecting expiry
|
||||
- Query log with retention limits, live-streamed over SSE
|
||||
- Web UI (embedded in the binary) and a REST API with a served OpenAPI spec
|
||||
- Prometheus-style `/metrics`, per-client rate limiting, disk-full
|
||||
self-protection
|
||||
|
||||
## Quickstart (docker compose)
|
||||
|
||||
Build the binary and image, seed a minimal configuration, start it:
|
||||
|
||||
```sh
|
||||
(cd web && npm ci && npm run build)
|
||||
zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
|
||||
|
||||
cd deploy/docker
|
||||
mkdir -p etc-nxdns
|
||||
cat > etc-nxdns/config.zon <<'EOF'
|
||||
.{
|
||||
.groups = .{ .{ .name = "default" } },
|
||||
.upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } },
|
||||
.web = .{ .password = "choose-a-real-password" },
|
||||
}
|
||||
EOF
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
DNS is on port 53, the web UI on <http://localhost:8080>. The config file
|
||||
seeds the database on first boot only; from then on the database is the
|
||||
truth and changes go through the UI, the API, or `nxdns export` /
|
||||
`nxdns import`. Full install instructions, including the systemd path and
|
||||
the Pi 5 recipe, are in [docs/operator.md](docs/operator.md).
|
||||
|
||||
## Building from source
|
||||
|
||||
Requires [Zig 0.16.0](https://ziglang.org/download/) and Node.js 24 (for
|
||||
the web UI). C dependencies (SQLite, mbedTLS) are vendored and built by
|
||||
`zig build`.
|
||||
|
||||
```sh
|
||||
(cd web && npm ci && npm run build) # web UI -> web/dist
|
||||
zig build -Dweb-dist=web/dist # native binary -> zig-out/bin/nxdns
|
||||
zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
|
||||
# static x86_64 + aarch64 musl binaries
|
||||
zig build test --summary all # unit tests
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- [docs/operator.md](docs/operator.md) — install, configure, back up,
|
||||
upgrade, troubleshoot
|
||||
- [docs/architecture.md](docs/architecture.md) — module map and design
|
||||
- [docs/config-reference.md](docs/config-reference.md) — every
|
||||
configuration field
|
||||
- [docs/api.md](docs/api.md) — REST API, auth and SSE
|
||||
- [PLAN.md](PLAN.md) and [specs/](specs/) — scope, design decisions and
|
||||
per-milestone contracts
|
||||
@@ -61,6 +61,9 @@ pub fn build(b: *std.Build) void {
|
||||
tests.root_module.addAnonymousImport("test_fixtures", .{
|
||||
.root_source_file = b.path("tests/fixtures/fixtures.zig"),
|
||||
});
|
||||
tests.root_module.addAnonymousImport("docs_files", .{
|
||||
.root_source_file = b.path("docs/docs.zig"),
|
||||
});
|
||||
tests.root_module.addAnonymousImport("web_assets", .{ .root_source_file = web_assets });
|
||||
const test_step = b.step("test", "Run the test suite");
|
||||
test_step.dependOn(&b.addRunArtifact(tests).step);
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# The Dockerfile copies only zig-out/cross out of the repository-root context,
|
||||
# and BuildKit transfers only referenced paths. This file guards the classic
|
||||
# (non-BuildKit) builder, which would otherwise send the whole tree: copy it to
|
||||
# the repository root as .dockerignore before building without BuildKit.
|
||||
*
|
||||
!zig-out/cross
|
||||
@@ -0,0 +1,33 @@
|
||||
# The binary is NOT compiled here. Build it first, from the repository root:
|
||||
#
|
||||
# (cd web && npm ci && npm run build)
|
||||
# zig build cross -Dweb-dist=web/dist -Doptimize=ReleaseSafe
|
||||
#
|
||||
# then build the image with the repository root as context:
|
||||
#
|
||||
# docker build -t nxdns -f deploy/docker/Dockerfile .
|
||||
#
|
||||
# The builder stage stages the CA bundle (upstream DoH/DoT verification rescans
|
||||
# the system store; a scratch image without one breaks every TLS upstream) and
|
||||
# maps the buildx TARGETARCH onto the zig cross-target directory.
|
||||
|
||||
FROM alpine:3.22 AS builder
|
||||
RUN apk add --no-cache ca-certificates
|
||||
ARG TARGETARCH
|
||||
COPY zig-out/cross /cross
|
||||
RUN mkdir -p /rootfs/etc/ssl/certs /rootfs/etc/nxdns /rootfs/var/lib/nxdns \
|
||||
&& cp /etc/ssl/certs/ca-certificates.crt /rootfs/etc/ssl/certs/ \
|
||||
&& case "${TARGETARCH:-amd64}" in \
|
||||
amd64) cp /cross/x86_64-linux-musl/nxdns /rootfs/nxdns ;; \
|
||||
arm64) cp /cross/aarch64-linux-musl/nxdns /rootfs/nxdns ;; \
|
||||
*) echo "unsupported TARGETARCH '${TARGETARCH}'" >&2; exit 1 ;; \
|
||||
esac \
|
||||
&& chown 65532:65532 /rootfs/var/lib/nxdns
|
||||
|
||||
FROM scratch
|
||||
COPY --from=builder /rootfs/ /
|
||||
USER 65532:65532
|
||||
VOLUME /var/lib/nxdns
|
||||
EXPOSE 53/udp 53/tcp 8080 443 853
|
||||
ENTRYPOINT ["/nxdns"]
|
||||
CMD ["run"]
|
||||
@@ -0,0 +1,31 @@
|
||||
services:
|
||||
nxdns:
|
||||
image: nxdns
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: deploy/docker/Dockerfile
|
||||
restart: unless-stopped
|
||||
# First boot needs ./etc-nxdns/config.zon with a `default` group and at
|
||||
# least one enabled upstream, or the container exits with code 2. The file
|
||||
# seeds the database once; after that the database is the truth and the
|
||||
# file is ignored.
|
||||
volumes:
|
||||
- ./etc-nxdns:/etc/nxdns:ro
|
||||
- nxdns-data:/var/lib/nxdns
|
||||
ports:
|
||||
- "53:53/udp"
|
||||
- "53:53/tcp"
|
||||
- "8080:8080"
|
||||
# DoH/DoT listeners, off by default in the config:
|
||||
# - "443:443"
|
||||
# - "853:853"
|
||||
# Per-network-namespace sysctl: lets uid 65532 bind port 53 inside the
|
||||
# container without CAP_NET_BIND_SERVICE.
|
||||
sysctls:
|
||||
net.ipv4.ip_unprivileged_port_start: 0
|
||||
# Do not point the host's resolv.conf at nxdns itself: the container's own
|
||||
# lookups (upstream DoH/DoT hostnames) would then depend on the service
|
||||
# they are trying to start.
|
||||
|
||||
volumes:
|
||||
nxdns-data:
|
||||
@@ -0,0 +1,49 @@
|
||||
[Unit]
|
||||
Description=nxdns DNS sinkhole
|
||||
Documentation=https://git.mial.net/mokhtar/nxdns
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=nxdns
|
||||
Group=nxdns
|
||||
ExecStart=/usr/local/bin/nxdns run
|
||||
|
||||
# nxdns logs to stderr by default; systemd captures it into the journal.
|
||||
StateDirectory=nxdns
|
||||
StateDirectoryMode=0700
|
||||
LogsDirectory=nxdns
|
||||
ConfigurationDirectory=nxdns
|
||||
|
||||
# Port 53 (and 443/853 when the DoH/DoT listeners are enabled).
|
||||
AmbientCapabilities=CAP_NET_BIND_SERVICE
|
||||
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
|
||||
|
||||
NoNewPrivileges=yes
|
||||
ProtectSystem=strict
|
||||
ProtectHome=yes
|
||||
PrivateTmp=yes
|
||||
PrivateDevices=yes
|
||||
ProtectKernelTunables=yes
|
||||
ProtectKernelModules=yes
|
||||
ProtectKernelLogs=yes
|
||||
ProtectControlGroups=yes
|
||||
ProtectClock=yes
|
||||
ProtectHostname=yes
|
||||
ProtectProc=invisible
|
||||
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
|
||||
RestrictNamespaces=yes
|
||||
RestrictRealtime=yes
|
||||
RestrictSUIDSGID=yes
|
||||
LockPersonality=yes
|
||||
MemoryDenyWriteExecute=yes
|
||||
UMask=0077
|
||||
SystemCallFilter=@system-service
|
||||
SystemCallArchitectures=native
|
||||
|
||||
Restart=on-failure
|
||||
RestartSec=2
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1 @@
|
||||
u nxdns - "nxdns DNS sinkhole"
|
||||
+169
@@ -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.
|
||||
@@ -0,0 +1,273 @@
|
||||
# Milestone 11: packaging, ops and docs (PLAN Phase 10)
|
||||
|
||||
Goal: systemd unit, Dockerfile + compose, and the four docs (operator, architecture,
|
||||
config-reference, API) — the documented deployment must work end-to-end; docs are
|
||||
drift-guarded where a guard is cheap and honest.
|
||||
|
||||
## Rulings (binding)
|
||||
|
||||
1. **Layout.** `deploy/systemd/nxdns.service` + `deploy/systemd/sysusers.conf`;
|
||||
`deploy/docker/{Dockerfile,compose.yaml,.dockerignore}`; `docs/{operator.md,
|
||||
architecture.md,config-reference.md,api.md}`; `README.md` at the root (the repo has
|
||||
none; a portfolio repo needs a front door — short: what, why, quickstart, doc links).
|
||||
PLAN.md:236 sketches docs/ subdirectories; single files need no subdirectories.
|
||||
|
||||
2. **API docs = hand-written `docs/api.md` + drift test.** No renderer is vendored
|
||||
(redoc/scalar are exactly the dependency liability AGENTS.md refuses), and a
|
||||
build-time YAML parser for rendering is scope the yaml does not justify — the yaml
|
||||
itself is already served unauthenticated at `GET /api/openapi.yaml` (routes.zig:49)
|
||||
and is the exhaustive contract. `docs/api.md` gives human-readable orientation:
|
||||
auth model (cookie session, login flow), rate limiting, error envelope, SSE
|
||||
semantics, then one line per operation (method, path, auth, one-sentence purpose)
|
||||
and a pointer to the yaml for schemas. A drift test asserts every served route
|
||||
appears textually in api.md (mirror of openapi.zig:34's guard). This satisfies
|
||||
m8 ruling 3's deferred "docs/api rendering" as the engineering call: rendered =
|
||||
readable, guarded, in-repo; not = a vendored JS bundle.
|
||||
|
||||
3. **Docs drift guards.** New `src/docs_drift_test.zig` (ORCHESTRATOR-owned, written
|
||||
after the doc sessions land): (a) every route in `router.routes` appears in
|
||||
docs/api.md; (b) every settings key from `model.toSettings` (the 44 keys) appears
|
||||
in docs/config-reference.md; (c) every CLI subcommand name appears in
|
||||
docs/operator.md. Docs embedded via a `docs_files` anonymous import added in
|
||||
build.zig (test_fixtures pattern, build.zig:61). Guards are textual-containment
|
||||
only — cheap, zero false authority.
|
||||
|
||||
4. **systemd unit.** `Type=simple` (no forking, shutdown.zig:35 handles SIGTERM),
|
||||
`ExecStart=/usr/local/bin/nxdns run`, stderr → journald (logging.zig:301 already
|
||||
states this; `logging.output=stderr` stays the default). Static system user `nxdns`
|
||||
via `deploy/systemd/sysusers.conf` (`u nxdns - "nxdns DNS sinkhole"`), NOT
|
||||
DynamicUser — the TLS key must be chown-able to a stable uid ("TLS keys readable by
|
||||
service user only", PLAN §19). `StateDirectory=nxdns` (0700 matches cli.zig:226),
|
||||
`LogsDirectory=nxdns` (covers logging.output=file; the binary does not create the
|
||||
directory, logging.zig:502), `ConfigurationDirectory=nxdns`.
|
||||
`AmbientCapabilities=CAP_NET_BIND_SERVICE` + `CapabilityBoundingSet=` the same
|
||||
(port 53; 443/853 covered by the same cap). Hardening: `NoNewPrivileges=yes`,
|
||||
`ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes`, `PrivateDevices=yes`,
|
||||
`ProtectKernelTunables/Modules/Logs=yes`, `ProtectControlGroups=yes`,
|
||||
`ProtectClock=yes`, `ProtectHostname=yes`, `ProtectProc=invisible`,
|
||||
`RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX`, `RestrictNamespaces=yes`,
|
||||
`RestrictRealtime=yes`, `RestrictSUIDSGID=yes`, `LockPersonality=yes`,
|
||||
`MemoryDenyWriteExecute=yes` (static Zig binary, no JIT), `UMask=0077`,
|
||||
`SystemCallFilter=@system-service`, `SystemCallArchitectures=native`,
|
||||
`Restart=on-failure`, `RestartSec=2`. No `ReadWritePaths` beyond what
|
||||
StateDirectory/LogsDirectory grant. Validate with `systemd-analyze verify` if the
|
||||
build host has it; report honestly if not.
|
||||
|
||||
5. **Docker.** Multi-stage: builder stage only stages `ca-certificates` (upstream
|
||||
TLS verification rescans the system CA bundle, tls_client.zig:216 — a scratch
|
||||
image without a bundle breaks every DoH/DoT upstream); final `FROM scratch` with
|
||||
the static musl binary, `/etc/ssl/certs/ca-certificates.crt`, a nonroot numeric
|
||||
`USER 65532:65532`, `VOLUME /var/lib/nxdns`, `EXPOSE 53/udp 53/tcp 8080 443 853`,
|
||||
`ENTRYPOINT ["/nxdns"]`, `CMD ["run"]`. The binary is NOT built inside the
|
||||
Dockerfile (the repo builds it with zig; the Dockerfile COPYes
|
||||
`zig-out/cross/$TARGETARCH-…/nxdns` via a build arg or buildx TARGETARCH mapping —
|
||||
keep it working for both arches). compose.yaml: ports 53:53/udp+tcp and 8080:8080
|
||||
(443/853 commented), bind-mount `./etc-nxdns:/etc/nxdns:ro`, named volume for
|
||||
`/var/lib/nxdns`, `sysctls: net.ipv4.ip_unprivileged_port_start=0` so the nonroot
|
||||
user binds 53 (per-netns sysctl; documented), `restart: unless-stopped`. First
|
||||
boot needs a seeded `/etc/nxdns/config.zon` with a `default` group + one enabled
|
||||
upstream or the container exits 2 (bootstrap.zig:38, app.zig:93) — operator.md and
|
||||
a compose comment both say so. Do NOT point the host's resolv.conf at nxdns
|
||||
itself for the container's own lookups.
|
||||
|
||||
6. **CI.** One added job `docker` in ci.yml: after building the x86_64 exe
|
||||
(ReleaseSafe, with the SPA dist like the cross job), `docker build` the image and
|
||||
run a container smoke (seed a minimal config.zon; `nxdns version` + boot + one
|
||||
`dig`-equivalent via the test client or `curl` on 8080/api/health; SIGTERM 0).
|
||||
No registry push — no publish step exists anywhere in this repo or the infra
|
||||
repo's CI, and registry credentials are an infra decision outside this repo.
|
||||
Manual publishing to git.mial.net stays possible and is documented in operator.md
|
||||
in one paragraph.
|
||||
|
||||
7. **Docs content contracts.**
|
||||
- operator.md: install (systemd path and docker path, both complete), first boot +
|
||||
config.zon seeding semantics (file seeds DB once, DB is truth thereafter,
|
||||
bootstrap.zig:38), auth setup (`web.password` hashed on import, never stored,
|
||||
export writes ""), TLS cert/key provisioning + 0600 expectations + the reload
|
||||
API/watcher, backup/restore = `nxdns export`/`import --force` (+ the 0600 export
|
||||
mode and why), upgrades (schema migration = install + restart, PLAN §20.11),
|
||||
data-dir layout table, exit codes (0/1/2/64, cli.zig:35), CLI reference (all six
|
||||
subcommands + flags), troubleshooting (exit 2 causes, `nxdns check` semantics
|
||||
incl. source-selection order cli.zig:511, disk-full degradation, port 53
|
||||
conflicts with systemd-resolved — include the disable recipe).
|
||||
- architecture.md: module map (the src/ inventory), the purity rule (dns/, filter/,
|
||||
local/, cache/ take bytes, no Io — AGENTS.md), std.Io injection + Threaded
|
||||
backend, data flow for one query (listener → handler → filter/cache/local →
|
||||
upstream → sink/logger), storage split (config.db truth / querylog.db expendable),
|
||||
web stack (std.http over TLS optional, SPA embedded via web_assets, SSE), cert
|
||||
hot-reload design (refcounted CertStore), failure-visibility doctrine (counters +
|
||||
/metrics over log spam). Concise — a map, not a novel.
|
||||
- config-reference.md: complete — every section/field with type, default, unit,
|
||||
validation range, and which subsystem consumes it; collections with required
|
||||
fields; DB-vs-file truth explanation; the `web.password`/`password_hash`
|
||||
exclusivity; `logging.level=.err` serializes as "error" (model.zig:154). The
|
||||
explorer inventory in this milestone's research is the skeleton; verify against
|
||||
model.zig/validate.zig while writing, do not trust the summary blindly.
|
||||
- api.md: per ruling 2.
|
||||
- README.md: ≤120 lines; what nxdns is, feature list (honest, shipping features
|
||||
only), quickstart (docker compose path), build-from-source (zig build, node for
|
||||
the SPA), doc links, license note if a LICENSE exists (do not invent one).
|
||||
|
||||
8. **No new runtime code.** This milestone adds zero behavior to the binary. The only
|
||||
src/ change is the orchestrator's docs_drift_test.zig + its build wiring. If a doc
|
||||
session finds a bug while documenting, it REPORTS it (no fix); the orchestrator
|
||||
triages.
|
||||
|
||||
9. **Pi 5 end-to-end**: the exit criterion runs on hardware this environment does not
|
||||
have. The deliverable here is: both suites green, docker smoke green on x86_64,
|
||||
`systemd-analyze verify` clean (or honestly reported unavailable), aarch64 binary
|
||||
built and statically verified (existing cross job). The operator doc's Pi 5 recipe
|
||||
is written to be executed by the user; the spec records this boundary explicitly.
|
||||
|
||||
## Sessions
|
||||
|
||||
U1, U3, U4, U5 parallel; U2 after U1 (documents the artifacts U1 produces);
|
||||
orchestrator wiring (ruling 3) after U3+U5.
|
||||
|
||||
## Session U1: deploy artifacts + CI
|
||||
|
||||
Owns `deploy/systemd/nxdns.service`, `deploy/systemd/sysusers.conf`,
|
||||
`deploy/docker/{Dockerfile,compose.yaml,.dockerignore}`, `.gitea/workflows/ci.yml`
|
||||
(one added job). Rulings 4, 5, 6. Verify: `systemd-analyze verify` (or report
|
||||
unavailable), local `docker build` + container smoke if the docker daemon is
|
||||
reachable (report honestly either way), `zig build test` untouched-green.
|
||||
|
||||
## Session U2: operator.md + README.md (after U1)
|
||||
|
||||
Owns `docs/operator.md`, `README.md`. Rulings 7 (operator + README). Reads U1's
|
||||
artifacts and the runtime/CLI facts from the code (verify against src/cli.zig,
|
||||
src/app.zig, src/config/bootstrap.zig — not from memory).
|
||||
|
||||
## Session U3: config-reference.md
|
||||
|
||||
Owns `docs/config-reference.md`. Ruling 7. Source of truth: src/config/model.zig +
|
||||
validate.zig + import/export/bootstrap. Every field, no sampling.
|
||||
|
||||
## Session U4: architecture.md
|
||||
|
||||
Owns `docs/architecture.md`. Ruling 7. Reads module headers; no deep dives needed
|
||||
beyond what the doc claims.
|
||||
|
||||
## Session U5: api.md
|
||||
|
||||
Owns `docs/api.md`. Rulings 2, 7. Source of truth: src/web/routes.zig (the served
|
||||
table: method, path, auth, limiter) + openapi.yaml summaries + auth.zig/sse.zig for
|
||||
the auth and SSE prose. Every route, no sampling.
|
||||
|
||||
## As built
|
||||
|
||||
**U1** delivered per rulings 4-6 with accepted deviations: `StateDirectoryMode=0700`
|
||||
(systemd defaults 0755; the binary cannot tighten a pre-existing directory) and
|
||||
`User=nxdns`/`Group=nxdns` added to the unit; the Dockerfile's builder stage also maps
|
||||
buildx TARGETARCH → cross-target dir and pre-chowns `/var/lib/nxdns` to 65532 (a named
|
||||
volume seeded from a root-owned image dir would be unwritable on first boot); compose
|
||||
gained a `build:` block; `deploy/docker/.dockerignore` is documentation-grade under
|
||||
BuildKit (only a root `.dockerignore` or `Dockerfile.dockerignore` is honored — the
|
||||
file's header says so). Verified: `systemd-analyze verify` clean modulo the off-host
|
||||
ExecStart path (an ExecStart=/bin/true copy verifies exit 0); full local docker build +
|
||||
smoke passed (binds 53 as uid 65532, /api/health ok, SIGTERM exit 0). The CI docker
|
||||
job probes both 127.0.0.1 and the container IP to survive either runner topology.
|
||||
Compose expects the operator-created seed at `deploy/docker/etc-nxdns/config.zon`
|
||||
(minimal: a `default` group + one enabled upstream), else exit 2.
|
||||
|
||||
**U2** delivered docs/operator.md (397 lines; systemd + docker + Pi 5 recipes, seeding
|
||||
semantics, auth, TLS, backup/restore, data-dir table, full CLI reference, exit codes,
|
||||
troubleshooting incl. the systemd-resolved DNSStubListener recipe) and README.md
|
||||
(72 lines, no license section — no LICENSE exists). All facts source-verified.
|
||||
|
||||
**U3** delivered docs/config-reference.md (12 scalar sections, 9 collections, DB-vs-file
|
||||
truth model, auth section, minimal + annotated examples) and surfaced five code
|
||||
discrepancies during writing (see fix wave below).
|
||||
|
||||
**U4** delivered docs/architecture.md (module map from the //! headers, purity rule
|
||||
with the honest exceptions, life-of-one-query pipeline verified against handler.zig,
|
||||
storage split, web stack, CertStore design, failure-visibility doctrine). Reported one
|
||||
stale comment (logging.zig:17 cited a moved cli.zig line) — orchestrator fixed the
|
||||
comment to cite start.zig:724 via std.process.Init.
|
||||
|
||||
**U5** delivered docs/api.md: all 56 operations (matches router.routes.len), auth /
|
||||
rate-limit / SSE prose, error envelope, openapi.yaml pointer. No code-vs-yaml
|
||||
discrepancies found.
|
||||
|
||||
**Orchestrator wiring (ruling 3)**: docs/docs.zig (embeds api.md, config-reference.md,
|
||||
operator.md), `docs_files` anonymous import on the test module in build.zig,
|
||||
src/docs_drift_test.zig with three containment guards (routes → api.md; toSettings
|
||||
keys → config-reference.md; the six subcommand names → operator.md), tests.zig import.
|
||||
|
||||
**Fix wave (orchestrator-triaged; ruling 8's no-runtime-code rule lifted for exactly
|
||||
these)** — U3's five discrepancies, triaged with stdlib evidence:
|
||||
1. `runtime.io_backend` DELETED end to end (model, settings handler + view, openapi,
|
||||
web types/SettingsPage/settingsDiff + tests, docs). Nothing consumed it — main uses
|
||||
init.io (stdlib Threaded, start.zig:724), and 0.16's std.Io.Evented has stubbed
|
||||
networking (Uring.zig netConnectIp → error.NetworkDown), so PLAN decision E's
|
||||
"io_uring via flag" is not deliverable at this tag. Re-add when std ships working
|
||||
evented net. Old DB rows warn-and-ignore via fromSettings' unknown-key path.
|
||||
2. `upstream.connect_timeout_ms` DELETED. No call site; the pool races the whole
|
||||
attempt against total_timeout (app.zig sets it from totalTimeout); Threaded panics
|
||||
on IpAddress.ConnectOptions.timeout != .none; std.http.Client has no knob. The
|
||||
validate cross-check is now total >= read only.
|
||||
3. `cache.size` KEPT: 0 is clean documented disabled behavior (put short-circuits;
|
||||
in-file test "a cache of zero entries stores nothing"). Doc row corrected.
|
||||
4. `dns.bind_ipv6` TIGHTENED: checkBind generalized to a BindFamily enum; dns.bind_ipv6
|
||||
requires an IPv6 literal (an IPv4 wildcard there made the v4 bind AddressInUse get
|
||||
swallowed with a false "dual-stack" log — silent IPv6 loss). web/TLS binds stay .any.
|
||||
5. doh/dot `readTimeout(.{})` sites KEPT: they are test fixtures; the real idle budget
|
||||
is the ruled 10s Options default. The doc claim was wrong and was removed.
|
||||
Settings key counts after deletion: toSettings emits 43 (incl. web.password_hash);
|
||||
the API-visible restart-required set is 42 (was 44).
|
||||
|
||||
## Review (Codex, as built)
|
||||
|
||||
Three rounds on one thread; round 3 returned "No findings."
|
||||
|
||||
Round 1 (5 important): stale-DB bind_ipv6 rows bypassed the new validate check at boot
|
||||
→ app.zig parseBind now enforces the IP family on both dns binds (BadBindAddress,
|
||||
exit 2, remedy in the message; the v4 side had the symmetric hole); app.zig's tests
|
||||
were not collected by tests.zig at all — the import line was added and the new test
|
||||
runs. operator.md's TLS recipe assumed the nxdns host user → Docker path now chowns
|
||||
65532:65532 numerically host-side (read-only bind mount). PLAN.md still promised the
|
||||
io_uring flag and connect_timeout_ms → synced (Io bullet records the drop with stdlib
|
||||
evidence; decision E row; example config). Drift guards were maskable → api.md guard
|
||||
anchors the full "| METHOD | `pattern` |" row per operation; operator.md guard anchors
|
||||
the "### `name" reference headings.
|
||||
|
||||
Round 2 (1 important, 1 minor): seed-permission guidance covered only web.password →
|
||||
now web.password or web.password_hash (a restored export); PLAN.md's "stubs all
|
||||
networking" overstated 0.16's Uring — now names the stubbed operations precisely.
|
||||
|
||||
Final gates: plain 1171/1284 passed, 113 skipped (integration-gated), 0 failed;
|
||||
integration 1280/1284, 4 skipped (live-network by design), 0 failed; cross ReleaseSafe
|
||||
with the SPA dist 18/18; web suite 121/121 with format/lint/typecheck clean.
|
||||
|
||||
## Module layout (new)
|
||||
|
||||
deploy/systemd/{nxdns.service,sysusers.conf}, deploy/docker/{Dockerfile,compose.yaml,
|
||||
.dockerignore}, docs/{operator,architecture,config-reference,api}.md, README.md,
|
||||
src/docs_drift_test.zig (orchestrator).
|
||||
|
||||
## File ownership
|
||||
|
||||
U1 deploy/* + ci.yml; U2 docs/operator.md + README.md; U3 docs/config-reference.md;
|
||||
U4 docs/architecture.md; U5 docs/api.md; orchestrator src/docs_drift_test.zig,
|
||||
build.zig (docs_files module), src/tests.zig.
|
||||
|
||||
## Acceptance (milestone complete)
|
||||
|
||||
- [ ] All files in the module layout exist with the ruling-7 content contracts met.
|
||||
- [ ] Docs drift tests pass: route coverage in api.md, settings-key coverage in
|
||||
config-reference.md, subcommand coverage in operator.md.
|
||||
- [ ] CI docker job builds the image and the container smoke passes (in CI; locally
|
||||
if the daemon is available).
|
||||
- [ ] `systemd-analyze verify deploy/systemd/nxdns.service` clean, or its
|
||||
unavailability recorded in the U1 report.
|
||||
- [ ] Both suites 0 failed; cross ReleaseSafe with the SPA dist green.
|
||||
- [ ] No runtime-behavior changes (git diff over src/ shows only docs_drift_test.zig
|
||||
+ wiring).
|
||||
|
||||
## Anti-requirements
|
||||
|
||||
- No vendored API-doc renderer (redoc/scalar/swagger-ui), no YAML parser.
|
||||
- No registry publish step; no k3s manifests (the infra repo owns deployment there).
|
||||
- No SIGHUP/reload feature, no env-var config, no new CLI flags — document what
|
||||
exists; report gaps instead of filling them.
|
||||
- No LICENSE invention; no badges or marketing prose in README.
|
||||
+59
-4
@@ -458,8 +458,8 @@ fn serve(r: cli.Runner, args: cli.RunArgs) !u8 {
|
||||
.reload_fn = reloadManager,
|
||||
};
|
||||
|
||||
const v6_bind = parseBind(r, cfg.dns.bind_ipv6, cfg.dns.port, "dns.bind_ipv6") catch |err| return err;
|
||||
const v4_bind = parseBind(r, cfg.dns.bind_ipv4, cfg.dns.port, "dns.bind_ipv4") catch |err| return err;
|
||||
const v6_bind = parseBind(r, cfg.dns.bind_ipv6, cfg.dns.port, "dns.bind_ipv6", .ip6) catch |err| return err;
|
||||
const v4_bind = parseBind(r, cfg.dns.bind_ipv4, cfg.dns.port, "dns.bind_ipv4", .ip4) catch |err| return err;
|
||||
|
||||
// IPv6 first, and the order is load-bearing — see `Listeners`.
|
||||
var udp6: ?udp_server.UdpServer = udp_server.UdpServer.bind(gpa, io, v6_bind, &h, .{}) catch |err| bound: {
|
||||
@@ -826,11 +826,66 @@ const Listeners = struct {
|
||||
tcp4: ?net.IpAddress,
|
||||
};
|
||||
|
||||
fn parseBind(r: cli.Runner, text: []const u8, port: u16, field: []const u8) !net.IpAddress {
|
||||
return net.IpAddress.parse(text, port) catch {
|
||||
const BindFamily = enum { ip4, ip6 };
|
||||
|
||||
/// `config/validate.checkBind` enforces the same family rule on import, check
|
||||
/// and settings PUT — but not on a config.db written before the rule existed,
|
||||
/// and `serve` loads that DB without re-validating. Boot is the last seam: a
|
||||
/// cross-family literal here would bind the wrong family's socket and make the
|
||||
/// real one fail with AddressInUse, silently losing a family.
|
||||
fn parseBind(
|
||||
r: cli.Runner,
|
||||
text: []const u8,
|
||||
port: u16,
|
||||
field: []const u8,
|
||||
family: BindFamily,
|
||||
) !net.IpAddress {
|
||||
const addr = net.IpAddress.parse(text, port) catch {
|
||||
r.err.print("{s}: '{s}' is not an IP address\n", .{ field, text }) catch {};
|
||||
return error.BadBindAddress;
|
||||
};
|
||||
const matches = switch (addr) {
|
||||
.ip4 => family == .ip4,
|
||||
.ip6 => family == .ip6,
|
||||
};
|
||||
if (!matches) {
|
||||
const digit: u8 = if (family == .ip4) '4' else '6';
|
||||
r.err.print(
|
||||
"{s}: '{s}' is not an IPv{c} address; re-import the configuration or correct it with a settings PUT\n",
|
||||
.{ field, text, digit },
|
||||
) catch {};
|
||||
return error.BadBindAddress;
|
||||
}
|
||||
return addr;
|
||||
}
|
||||
|
||||
test "parseBind refuses a bind address of the wrong family" {
|
||||
var out_buf: [8]u8 = undefined;
|
||||
var err_buf: [256]u8 = undefined;
|
||||
var out: Writer = .fixed(&out_buf);
|
||||
var err_writer: Writer = .fixed(&err_buf);
|
||||
const r: cli.Runner = .{
|
||||
.io = std.testing.io,
|
||||
.gpa = std.testing.allocator,
|
||||
.out = &out,
|
||||
.err = &err_writer,
|
||||
};
|
||||
|
||||
_ = try parseBind(r, "0.0.0.0", 53, "dns.bind_ipv4", .ip4);
|
||||
_ = try parseBind(r, "::", 53, "dns.bind_ipv6", .ip6);
|
||||
|
||||
try std.testing.expectError(
|
||||
error.BadBindAddress,
|
||||
parseBind(r, "0.0.0.0", 53, "dns.bind_ipv6", .ip6),
|
||||
);
|
||||
try std.testing.expectError(
|
||||
error.BadBindAddress,
|
||||
parseBind(r, "::", 53, "dns.bind_ipv4", .ip4),
|
||||
);
|
||||
|
||||
const printed = err_writer.buffered();
|
||||
try std.testing.expect(std.mem.containsAtLeast(u8, printed, 1, "is not an IPv6 address"));
|
||||
try std.testing.expect(std.mem.containsAtLeast(u8, printed, 1, "is not an IPv4 address"));
|
||||
}
|
||||
|
||||
fn reportBind(r: cli.Runner, which: []const u8, addr: net.IpAddress, err: anyerror) anyerror {
|
||||
|
||||
+2
-37
@@ -18,7 +18,6 @@ const std = @import("std");
|
||||
const Allocator = std.mem.Allocator;
|
||||
|
||||
pub const Config = struct {
|
||||
runtime: Runtime = .{},
|
||||
upstream: Upstream = .{},
|
||||
dns: Dns = .{},
|
||||
blocking: Blocking = .{},
|
||||
@@ -42,28 +41,7 @@ pub const Config = struct {
|
||||
forward_zones: []const ForwardZone = &.{},
|
||||
};
|
||||
|
||||
pub const IoBackend = enum {
|
||||
threaded,
|
||||
evented,
|
||||
|
||||
pub fn toDb(self: IoBackend) []const u8 {
|
||||
return switch (self) {
|
||||
.threaded => "threaded",
|
||||
.evented => "evented",
|
||||
};
|
||||
}
|
||||
|
||||
pub fn fromDb(text: []const u8) ?IoBackend {
|
||||
if (std.mem.eql(u8, text, "threaded")) return .threaded;
|
||||
if (std.mem.eql(u8, text, "evented")) return .evented;
|
||||
return null;
|
||||
}
|
||||
};
|
||||
|
||||
pub const Runtime = struct { io_backend: IoBackend = .threaded };
|
||||
|
||||
pub const Upstream = struct {
|
||||
connect_timeout_ms: u32 = 2000,
|
||||
read_timeout_ms: u32 = 3000,
|
||||
total_timeout_ms: u32 = 5000,
|
||||
};
|
||||
@@ -318,10 +296,6 @@ comptime {
|
||||
assertFits(u32, 1024 * 1024, u64); // MiB conversions
|
||||
}
|
||||
|
||||
pub fn connectTimeout(u: Upstream) std.Io.Duration {
|
||||
return .{ .nanoseconds = @as(i96, u.connect_timeout_ms) * std.time.ns_per_ms };
|
||||
}
|
||||
|
||||
pub fn readTimeout(u: Upstream) std.Io.Duration {
|
||||
return .{ .nanoseconds = @as(i96, u.read_timeout_ms) * std.time.ns_per_ms };
|
||||
}
|
||||
@@ -506,8 +480,6 @@ const expected_keys = [_][]const u8{
|
||||
"logging.output",
|
||||
"logging.query_log_buffer_max",
|
||||
"logging.retention_days",
|
||||
"runtime.io_backend",
|
||||
"upstream.connect_timeout_ms",
|
||||
"upstream.read_timeout_ms",
|
||||
"upstream.total_timeout_ms",
|
||||
"web.api_localhost_exempt",
|
||||
@@ -558,8 +530,7 @@ test "toSettings never emits web.password" {
|
||||
test "toSettings and fromSettings round-trip a non-default config" {
|
||||
const gpa = testing.allocator;
|
||||
const original: Config = .{
|
||||
.runtime = .{ .io_backend = .evented },
|
||||
.upstream = .{ .connect_timeout_ms = 111, .read_timeout_ms = 222, .total_timeout_ms = 333 },
|
||||
.upstream = .{ .read_timeout_ms = 222, .total_timeout_ms = 333 },
|
||||
.dns = .{
|
||||
.bind_ipv4 = "127.0.0.1",
|
||||
.bind_ipv6 = "::1",
|
||||
@@ -697,7 +668,6 @@ fn expectEnumRoundTrip(comptime E: type) !void {
|
||||
}
|
||||
|
||||
test "every toDb and fromDb enum pair round-trips over all tags" {
|
||||
try expectEnumRoundTrip(IoBackend);
|
||||
try expectEnumRoundTrip(BlockResponse);
|
||||
try expectEnumRoundTrip(EcsMode);
|
||||
try expectEnumRoundTrip(LogLevel);
|
||||
@@ -715,10 +685,6 @@ test "RecordType stores the uppercase DDL spelling" {
|
||||
}
|
||||
|
||||
test "unit conversions" {
|
||||
try testing.expectEqual(
|
||||
@as(i96, 2000) * std.time.ns_per_ms,
|
||||
connectTimeout(.{}).nanoseconds,
|
||||
);
|
||||
try testing.expectEqual(
|
||||
@as(i96, 3000) * std.time.ns_per_ms,
|
||||
readTimeout(.{}).nanoseconds,
|
||||
@@ -737,13 +703,12 @@ test "unit conversions" {
|
||||
|
||||
test "unit conversions at the field maximum do not overflow" {
|
||||
const max_upstream: Upstream = .{
|
||||
.connect_timeout_ms = std.math.maxInt(u32),
|
||||
.read_timeout_ms = std.math.maxInt(u32),
|
||||
.total_timeout_ms = std.math.maxInt(u32),
|
||||
};
|
||||
try testing.expectEqual(
|
||||
@as(i96, std.math.maxInt(u32)) * std.time.ns_per_ms,
|
||||
connectTimeout(max_upstream).nanoseconds,
|
||||
readTimeout(max_upstream).nanoseconds,
|
||||
);
|
||||
try testing.expectEqual(
|
||||
@as(i64, std.math.maxInt(u16)) * 3600,
|
||||
|
||||
+30
-13
@@ -199,21 +199,20 @@ const max_rate_window_seconds = 3_600;
|
||||
|
||||
fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void {
|
||||
const up = cfg.upstream;
|
||||
try checkTimeout(diags, up.connect_timeout_ms, "upstream.connect_timeout_ms");
|
||||
try checkTimeout(diags, up.read_timeout_ms, "upstream.read_timeout_ms");
|
||||
try checkTimeout(diags, up.total_timeout_ms, "upstream.total_timeout_ms");
|
||||
if (up.total_timeout_ms < up.connect_timeout_ms or up.total_timeout_ms < up.read_timeout_ms) {
|
||||
if (up.total_timeout_ms < up.read_timeout_ms) {
|
||||
try diags.add(
|
||||
error.BadTimeout,
|
||||
"upstream.total_timeout_ms",
|
||||
.{},
|
||||
"total budget {d}ms is below connect {d}ms or read {d}ms",
|
||||
.{ up.total_timeout_ms, up.connect_timeout_ms, up.read_timeout_ms },
|
||||
"total budget {d}ms is below read {d}ms",
|
||||
.{ up.total_timeout_ms, up.read_timeout_ms },
|
||||
);
|
||||
}
|
||||
|
||||
try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", true);
|
||||
try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", false);
|
||||
try checkBind(diags, cfg.dns.bind_ipv4, "dns.bind_ipv4", .ip4);
|
||||
try checkBind(diags, cfg.dns.bind_ipv6, "dns.bind_ipv6", .ip6);
|
||||
try checkPort(diags, cfg.dns.port, "dns.port");
|
||||
if (cfg.dns.rate_limit < 1) {
|
||||
try diags.add(error.BadRateLimit, "dns.rate_limit", .{}, "must be at least 1", .{});
|
||||
@@ -248,7 +247,7 @@ fn checkScalars(cfg: Config, diags: *Diagnostics) error{OutOfMemory}!void {
|
||||
);
|
||||
}
|
||||
|
||||
try checkBind(diags, cfg.web.bind, "web.bind", false);
|
||||
try checkBind(diags, cfg.web.bind, "web.bind", .any);
|
||||
try checkPort(diags, cfg.web.port, "web.port");
|
||||
if (cfg.web.password.len != 0 and cfg.web.password_hash.len != 0) {
|
||||
try diags.add(
|
||||
@@ -339,18 +338,30 @@ fn checkTimeout(diags: *Diagnostics, value: u32, comptime path: []const u8) erro
|
||||
}
|
||||
}
|
||||
|
||||
const BindFamily = enum { ip4, ip6, any };
|
||||
|
||||
/// `dns.bind_ipv4` and `dns.bind_ipv6` each name one socket of the dual-stack
|
||||
/// pair, so each must be a literal of its own family: an IPv4 wildcard in
|
||||
/// `bind_ipv6` would bind IPv4 as the "v6" socket and make the real IPv4 bind
|
||||
/// fail with AddressInUse — the IPv6 service silently disappears.
|
||||
fn checkBind(
|
||||
diags: *Diagnostics,
|
||||
text: []const u8,
|
||||
comptime path: []const u8,
|
||||
comptime require_ip4: bool,
|
||||
comptime family: BindFamily,
|
||||
) error{OutOfMemory}!void {
|
||||
const addr = NetAddress.parse(text) catch {
|
||||
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IP address", .{text});
|
||||
return;
|
||||
};
|
||||
if (require_ip4 and std.meta.activeTag(addr) != NetAddress.ip4) {
|
||||
switch (family) {
|
||||
.ip4 => if (std.meta.activeTag(addr) != NetAddress.ip4) {
|
||||
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv4 address", .{text});
|
||||
},
|
||||
.ip6 => if (std.meta.activeTag(addr) != NetAddress.ip6) {
|
||||
try diags.add(error.BadBindAddress, path, .{}, "'{s}' is not an IPv6 address", .{text});
|
||||
},
|
||||
.any => {},
|
||||
}
|
||||
}
|
||||
|
||||
@@ -359,7 +370,7 @@ fn checkTlsEndpoint(
|
||||
endpoint: model.TlsEndpoint,
|
||||
comptime section: []const u8,
|
||||
) error{OutOfMemory}!void {
|
||||
try checkBind(diags, endpoint.bind, section ++ ".bind", false);
|
||||
try checkBind(diags, endpoint.bind, section ++ ".bind", .any);
|
||||
try checkPort(diags, endpoint.port, section ++ ".port");
|
||||
if (!endpoint.enabled) return;
|
||||
// Readability of the files is `nxdns check`'s job, not the pure validator's.
|
||||
@@ -1162,11 +1173,11 @@ test "error.BadPort" {
|
||||
|
||||
test "error.BadTimeout" {
|
||||
var cfg = baseConfig();
|
||||
cfg.upstream.connect_timeout_ms = 10;
|
||||
try expectProblem(cfg, error.BadTimeout, "upstream.connect_timeout_ms");
|
||||
cfg.upstream.read_timeout_ms = 10;
|
||||
try expectProblem(cfg, error.BadTimeout, "upstream.read_timeout_ms");
|
||||
|
||||
var budget = baseConfig();
|
||||
budget.upstream = .{ .connect_timeout_ms = 4000, .read_timeout_ms = 4000, .total_timeout_ms = 1000 };
|
||||
budget.upstream = .{ .read_timeout_ms = 4000, .total_timeout_ms = 1000 };
|
||||
try expectProblem(budget, error.BadTimeout, "upstream.total_timeout_ms");
|
||||
}
|
||||
|
||||
@@ -1214,6 +1225,12 @@ test "error.BadBindAddress" {
|
||||
try expectProblem(web, error.BadBindAddress, "web.bind");
|
||||
}
|
||||
|
||||
test "error.BadBindAddress on an IPv4 literal in dns.bind_ipv6" {
|
||||
var cfg = baseConfig();
|
||||
cfg.dns.bind_ipv6 = "0.0.0.0";
|
||||
try expectProblem(cfg, error.BadBindAddress, "dns.bind_ipv6");
|
||||
}
|
||||
|
||||
test "error.MissingCertPath" {
|
||||
var cfg = baseConfig();
|
||||
cfg.doh_server = .{ .enabled = true, .cert_path = "" };
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
//! Textual-containment guards that keep the hand-written docs honest
|
||||
//! (milestone-11 ruling 3). They assert presence, not correctness — the same
|
||||
//! contract as openapi.zig's route guard.
|
||||
|
||||
const std = @import("std");
|
||||
const docs = @import("docs_files");
|
||||
const routes = @import("web/routes.zig");
|
||||
const model = @import("config/model.zig");
|
||||
|
||||
test "every served operation has its own table row in docs/api.md" {
|
||||
const gpa = std.testing.allocator;
|
||||
for (routes.table) |route| {
|
||||
// Matches one full method + path cell pair ("| GET | `/api/groups` |"),
|
||||
// so neither a same-path sibling method nor a longer-path prefix can
|
||||
// satisfy the check for a missing operation.
|
||||
const needle = try std.fmt.allocPrint(gpa, "| {s} | `{s}` |", .{
|
||||
@tagName(route.method), route.pattern,
|
||||
});
|
||||
defer gpa.free(needle);
|
||||
if (std.mem.indexOf(u8, docs.api_md, needle) == null) {
|
||||
std.debug.print("operation row missing from docs/api.md: {s}\n", .{needle});
|
||||
return error.OperationMissingFromApiDoc;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
test "every settings key appears in docs/config-reference.md" {
|
||||
const gpa = std.testing.allocator;
|
||||
var pairs: std.ArrayList(model.SettingPair) = .empty;
|
||||
defer {
|
||||
model.freeSettings(gpa, pairs.items);
|
||||
pairs.deinit(gpa);
|
||||
}
|
||||
try model.toSettings(.{}, gpa, &pairs);
|
||||
for (pairs.items) |pair| {
|
||||
if (std.mem.indexOf(u8, docs.config_reference_md, pair.key) == null) {
|
||||
std.debug.print("settings key missing from docs/config-reference.md: {s}\n", .{pair.key});
|
||||
return error.SettingsKeyMissingFromConfigDoc;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
test "every cli subcommand has its own reference heading in docs/operator.md" {
|
||||
const gpa = std.testing.allocator;
|
||||
const subcommands = [_][]const u8{ "run", "check", "export", "import", "version", "help" };
|
||||
for (subcommands) |name| {
|
||||
// Anchors on the reference-section heading ("### `import FILE`" starts
|
||||
// with "### `import"), so prose mentions elsewhere cannot mask a
|
||||
// removed command section.
|
||||
const needle = try std.fmt.allocPrint(gpa, "### `{s}", .{name});
|
||||
defer gpa.free(needle);
|
||||
if (std.mem.indexOf(u8, docs.operator_md, needle) == null) {
|
||||
std.debug.print("subcommand heading missing from docs/operator.md: {s}\n", .{needle});
|
||||
return error.SubcommandMissingFromOperatorDoc;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -14,8 +14,9 @@
|
||||
//! need no `Io` because they read `std.Options.debug_io` (debug.zig:283), they
|
||||
//! are documented as recursive (debug.zig:263-270), and `Io/Threaded.zig`
|
||||
//! implements that recursion per OS thread (Threaded.zig:13787-13796). nxdns
|
||||
//! runs a `std.Io.Threaded` instance (cli.zig:793), so one task is one thread
|
||||
//! and the recursion holds. Taking it across the file writes as well keeps the
|
||||
//! runs on the `std.Io.Threaded` instance the stdlib start code constructs
|
||||
//! (start.zig:724, handed to `main` via `std.process.Init`), so one task is
|
||||
//! one thread and the recursion holds. Taking it across the file writes as well keeps the
|
||||
//! file path and the stderr fallback path from interleaving with each other,
|
||||
//! with `std.Progress`, or with a panic dump.
|
||||
//!
|
||||
|
||||
@@ -2,6 +2,7 @@ const std = @import("std");
|
||||
|
||||
comptime {
|
||||
_ = @import("main.zig");
|
||||
_ = @import("app.zig");
|
||||
_ = @import("version.zig");
|
||||
_ = @import("dns/types.zig");
|
||||
_ = @import("dns/header.zig");
|
||||
@@ -112,6 +113,7 @@ comptime {
|
||||
_ = @import("server/dot_server.zig");
|
||||
_ = @import("server/doh_server.zig");
|
||||
_ = @import("web/handlers/certs.zig");
|
||||
_ = @import("docs_drift_test.zig");
|
||||
}
|
||||
|
||||
extern fn sqlite3_libversion() [*:0]const u8;
|
||||
|
||||
@@ -189,7 +189,6 @@ fn newPassword(patch: Patch) ?[]const u8 {
|
||||
// the read shape
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const RuntimeView = struct { io_backend: []const u8 };
|
||||
const BlockingView = struct { response: []const u8, ttl: u32 };
|
||||
const EdnsView = struct { ecs_mode: []const u8 };
|
||||
|
||||
@@ -219,7 +218,6 @@ const WebView = struct {
|
||||
};
|
||||
|
||||
pub const View = struct {
|
||||
runtime: RuntimeView,
|
||||
upstream: model.Upstream,
|
||||
dns: model.Dns,
|
||||
blocking: BlockingView,
|
||||
@@ -235,7 +233,6 @@ pub const View = struct {
|
||||
|
||||
pub fn view(cfg: model.Config) View {
|
||||
return .{
|
||||
.runtime = .{ .io_backend = cfg.runtime.io_backend.toDb() },
|
||||
.upstream = cfg.upstream,
|
||||
.dns = cfg.dns,
|
||||
.blocking = .{ .response = cfg.blocking.response.toDb(), .ttl = cfg.blocking.ttl },
|
||||
@@ -469,13 +466,11 @@ test "the read shape spells every enum the way the database does" {
|
||||
.logging = .{ .level = .err, .output = .file },
|
||||
.blocking = .{ .response = .nxdomain },
|
||||
.edns = .{ .ecs_mode = .forward },
|
||||
.runtime = .{ .io_backend = .evented },
|
||||
});
|
||||
try testing.expectEqualStrings("error", rendered.logging.level);
|
||||
try testing.expectEqualStrings("file", rendered.logging.output);
|
||||
try testing.expectEqualStrings("nxdomain", rendered.blocking.response);
|
||||
try testing.expectEqualStrings("forward", rendered.edns.ecs_mode);
|
||||
try testing.expectEqualStrings("evented", rendered.runtime.io_backend);
|
||||
try testing.expect(!rendered.web.auth_enabled);
|
||||
|
||||
const with_password = view(.{ .web = .{ .password_hash = "$argon2id$v=19$m=19456,t=2,p=1$a$b" } });
|
||||
|
||||
+2
-15
@@ -2088,20 +2088,12 @@ components:
|
||||
|
||||
Settings:
|
||||
type: object
|
||||
required: [runtime, upstream, dns, blocking, cache, web, doh_server, dot_server, edns, logging, disk, blocklist_update]
|
||||
required: [upstream, dns, blocking, cache, web, doh_server, dot_server, edns, logging, disk, blocklist_update]
|
||||
properties:
|
||||
runtime:
|
||||
type: object
|
||||
required: [io_backend]
|
||||
properties:
|
||||
io_backend:
|
||||
type: string
|
||||
enum: [threaded, evented]
|
||||
upstream:
|
||||
type: object
|
||||
required: [connect_timeout_ms, read_timeout_ms, total_timeout_ms]
|
||||
required: [read_timeout_ms, total_timeout_ms]
|
||||
properties:
|
||||
connect_timeout_ms: { type: integer }
|
||||
read_timeout_ms: { type: integer }
|
||||
total_timeout_ms: { type: integer }
|
||||
dns:
|
||||
@@ -2213,14 +2205,9 @@ components:
|
||||
the write-only `web.password`. `web.password_hash` is rejected as
|
||||
an unknown field.
|
||||
properties:
|
||||
runtime:
|
||||
type: object
|
||||
properties:
|
||||
io_backend: { type: string }
|
||||
upstream:
|
||||
type: object
|
||||
properties:
|
||||
connect_timeout_ms: { type: integer }
|
||||
read_timeout_ms: { type: integer }
|
||||
total_timeout_ms: { type: integer }
|
||||
dns:
|
||||
|
||||
@@ -525,8 +525,7 @@ const TlsEndpointView = struct {
|
||||
/// response never carries `web.password` or `web.password_hash` (ruling 16).
|
||||
const SettingsView = struct {
|
||||
settings: struct {
|
||||
runtime: struct { io_backend: []const u8 },
|
||||
upstream: struct { connect_timeout_ms: u32, read_timeout_ms: u32, total_timeout_ms: u32 },
|
||||
upstream: struct { read_timeout_ms: u32, total_timeout_ms: u32 },
|
||||
dns: struct {
|
||||
bind_ipv4: []const u8,
|
||||
bind_ipv6: []const u8,
|
||||
|
||||
@@ -10,8 +10,7 @@ import type { Settings, SettingsPatch } from "@/lib/types";
|
||||
|
||||
function baseSettings(): Settings {
|
||||
return {
|
||||
runtime: { io_backend: "threaded" },
|
||||
upstream: { connect_timeout_ms: 2000, read_timeout_ms: 3000, total_timeout_ms: 5000 },
|
||||
upstream: { read_timeout_ms: 3000, total_timeout_ms: 5000 },
|
||||
dns: { bind_ipv4: "0.0.0.0", bind_ipv6: "::", port: 53, rate_limit: 100, rate_window_seconds: 60 },
|
||||
blocking: { response: "zero", ttl: 300 },
|
||||
cache: { size: 10000, negative_ttl_max: 300 },
|
||||
|
||||
@@ -33,12 +33,10 @@ const TLS_FIELDS: readonly FieldDef[] = [
|
||||
];
|
||||
|
||||
const SECTIONS: readonly SectionDef[] = [
|
||||
{ section: "runtime", title: "Runtime", fields: [{ key: "io_backend", kind: ["threaded", "evented"] }] },
|
||||
{
|
||||
section: "upstream",
|
||||
title: "Upstream",
|
||||
fields: [
|
||||
{ key: "connect_timeout_ms", kind: "number" },
|
||||
{ key: "read_timeout_ms", kind: "number" },
|
||||
{ key: "total_timeout_ms", kind: "number" },
|
||||
],
|
||||
|
||||
@@ -3,8 +3,7 @@ import type { Settings } from "@/lib/types";
|
||||
|
||||
function baseSettings(): Settings {
|
||||
return {
|
||||
runtime: { io_backend: "threaded" },
|
||||
upstream: { connect_timeout_ms: 2000, read_timeout_ms: 3000, total_timeout_ms: 5000 },
|
||||
upstream: { read_timeout_ms: 3000, total_timeout_ms: 5000 },
|
||||
dns: { bind_ipv4: "0.0.0.0", bind_ipv6: "::", port: 53, rate_limit: 100, rate_window_seconds: 60 },
|
||||
blocking: { response: "zero", ttl: 300 },
|
||||
cache: { size: 10000, negative_ttl_max: 300 },
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { Settings, SettingsPatch } from "@/lib/types";
|
||||
|
||||
const SECTIONS = [
|
||||
"runtime",
|
||||
"upstream",
|
||||
"dns",
|
||||
"blocking",
|
||||
|
||||
@@ -313,11 +313,7 @@ export interface TlsListenerSettings {
|
||||
}
|
||||
|
||||
export interface Settings {
|
||||
runtime: {
|
||||
io_backend: "threaded" | "evented";
|
||||
};
|
||||
upstream: {
|
||||
connect_timeout_ms: number;
|
||||
read_timeout_ms: number;
|
||||
total_timeout_ms: number;
|
||||
};
|
||||
@@ -388,7 +384,6 @@ export interface TlsListenerPatch {
|
||||
|
||||
/** Partial update; `web.password` is write-only, `web.auth_enabled` is never sent. */
|
||||
export interface SettingsPatch {
|
||||
runtime?: Partial<Settings["runtime"]>;
|
||||
upstream?: Partial<Settings["upstream"]>;
|
||||
dns?: Partial<Settings["dns"]>;
|
||||
blocking?: Partial<Settings["blocking"]>;
|
||||
|
||||
Reference in New Issue
Block a user