nxdns/CHANGELOG.md

Changelog

All notable changes to nxdns are recorded here. The format follows Keep a Changelog, and the project uses Semantic Versioning.

Sections are written by hand. Nothing here is generated from commit messages: the point of the file is to say what changed for an operator, which a commit subject rarely does.

[Unreleased]

Added

• Declarative configuration for IaC. nxdns run --config=<file> makes the file the sole source of configuration: every boot converges the database to it in one transaction, preserving blocklist downloads, compiled lists and client history, so an unchanged file costs zero downloads and zero writes. Bare nxdns run keeps the database (and the web UI) in charge, exactly as before. In file mode the web UI is read-only for configuration and says so; runtime actions (pause, blocklist refresh, certificate reload) stay live. GET /api/settings reports which authority governs the process.
• nxdns import now refuses a file whose application would delete configuration rows, names the tables and counts, and applies it only with the new --allow-delete flag. Additive and edit-in-place imports need no flag.

Changed

• Breaking: nxdns run --config <file> changed meaning. It used to seed the database once and then ignore the file; it now makes the file the authority on every boot, which deletes any configuration the file does not declare — including edits made through the web UI since the seed. Before upgrading a unit that carries --config: either drop the flag to keep the database in charge, or adopt file mode with the sequence in the upgrade guide. Order matters there: export the file with the NEW binary (stopped).
• Breaking: 0.0.1 exports are refused by this version. A 0.0.1 nxdns export writes both .password = "" and the stored .password_hash, and this version refuses a file that carries both. This bites any old export — an adoption file or a configuration backup fed to nxdns import alike. Fix an existing export by deleting its .password = "" line (keep the .password_hash line). Take fresh backups with the new binary.
• Breaking: the offline password-change recipe changed. Setting .password = "new" together with .password_hash = "" is now refused (empty password_hash is an explicit "disable authentication", and the two fields cannot both be present). To change the password in the file: set .password and delete the .password_hash line entirely.
• nxdns import --force is renamed --allow-delete.
• A fresh install no longer seeds from /etc/nxdns/config.zon by presence. Use nxdns import once, or run in file mode with --config.

[0.0.1] - 2026-08-09

First release. Everything below is new.

Added

• Forwarding DNS server. UDP and TCP listeners with a wire-format parser and encoder written against RFC 1035 and EDNS(0), a bounded worker model, per-client rate limiting and a pause control that stops filtering without stopping resolution.
• Encrypted upstreams. DNS-over-HTTPS and DNS-over-TLS clients over a pool that tracks per-upstream health and fails over, with SNI and certificate verification driven by a per-upstream TLS name.
• DoH and DoT endpoints. nxdns also answers as an encrypted resolver, with a certificate store that reloads on disk changes and through the API, so renewals do not need a restart.
• Blocklist filtering. Subscriptions in hosts, plain-domain and Adblock-Plus-style formats, compiled into a compact matcher; per-group allow and block rules with wildcards; safe-search enforcement.
• Per-client policy groups. Clients are identified by address and assigned to groups, so the filtering a device gets depends on which device it is.
• Local DNS. Local A/AAAA/CNAME/PTR records and conditional forwarding of internal zones to another resolver.
• Cache. A bounded in-memory cache that respects upstream TTLs and expires entries rather than serving them stale.
• Query log. Queries land in SQLite under a retention policy in both rows and days, with disk-full self-protection that degrades instead of corrupting, and a live SSE stream of the same events.
• Web UI and REST API. A React single-page admin UI embedded in the binary, a REST API with a served OpenAPI document, session authentication, API rate limiting and Prometheus-style /metrics.
• Configuration. A ZON configuration file seeds the database on first boot; after that the database is the truth, and nxdns export / nxdns import move configuration in and out. nxdns check validates a file without starting.
• CLI. run, check, export, import, version and help.
• Packaging. A hardened systemd unit with a sysusers fragment, and a FROM scratch container image holding the binary, a CA bundle and the licence files, assembled by a builder stage pinned to alpine:3.22 by digest. Nothing from Alpine ships in the published image except that CA bundle.
• Releases. Tags publish five assets — static musl tarballs for x86_64-linux-musl and aarch64-linux-musl, IMAGE-DIGEST.txt naming the multi-architecture container image by digest, SHA256SUMS.txt over those three, and SHA256SUMS.txt.asc, a detached signature over the checksum file. zig build dist and zig build verify-dist produce and check the same artifacts on a laptop.
• Licensing. EUPL-1.2, with a THIRD-PARTY-NOTICES file in every tarball and image assembled from a reviewed inventory of what the artifacts contain.
• Documentation. A Diátaxis split — tutorial, how-to, reference, explanation — with drift guards that fail the build when the reference pages fall behind the code.