nxdns

nxdns is a DNS sinkhole for your LAN. It blocks the names you do not want, and forwards the rest over an encrypted connection.

flowchart LR
    devices["Your devices"] -- "DNS query" --> nxdns["nxdns"]
    nxdns -- "answer" --> devices
    nxdns -- "allowed" --> upstream["Upstream resolvers<br/>DoH / DoT"]
    upstream -- "answer" --> nxdns
    nxdns -- "blocked" --> sink["0.0.0.0 / NXDOMAIN"]

One static Zig binary. SQLite holds the state and the query log, which the web UI, the REST API and /metrics read.

Features

• Blocklist filtering: subscribe to hosts, domain and Adblock Plus lists — whose @@ exception lines are honoured — plus your own allow and block rules, exact, wildcard (*.example.com) or regular expression
• Two configuration modes: a database the web UI edits, or a ZON file you keep in git and converge onto at every start
• 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

Install

No release exists yet. This repository has no tags, nothing has been published to https://git.mial.net/mokhtar/nxdns/releases, and no container image has been pushed. Every release URL on this page and in the how-to guides is a 404 today, and docker pull finds nothing. Until the first tag ships, building from source is the only way to get nxdns.

What a tag will publish, once one exists: five assets — two static musl tarballs (nxdns-<version>-x86_64-linux-musl.tar.gz, nxdns-<version>-aarch64-linux-musl.tar.gz), IMAGE-DIGEST.txt naming the multi-architecture container image by digest, SHA256SUMS.txt covering those three files, and SHA256SUMS.txt.asc, a detached OpenPGP signature over the checksum file. Verify what you downloaded before you run it: docs/how-to/verify-a-release.md, which also says what that signature does and does not prove.

Quickstart (docker compose)

Write a minimal configuration and start the published image. This is what the first release will make possible; it does not work today, because there is no image in the registry to pull:

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
NXDNS_VERSION=<version> docker compose up -d

The compose file defaults to :latest; pin a version for anything you intend to keep running. To run it before a release exists, build the image yourself and name it — NXDNS_IMAGE=nxdns docker compose up -d — as docs/how-to/install-with-docker.md describes. DNS is on port 53, the web UI on http://localhost:8080.

The compose file runs nxdns run --config=/etc/nxdns/config.zon, which makes that file the configuration: every start reconciles the database onto it, and the UI refuses configuration edits. Edit the file and restart to change anything. Drop the command: line to run bare nxdns run instead, where the database is the configuration and changes go through the UI, the API, or nxdns export / nxdns import — the packaged systemd unit does that. Which mode is live is printed at every start (authority: database / authority: file (<path>)); see docs/explanation/configuration-model.md.

Full install instructions, including the systemd path and the Pi 5 recipe, are in docs/how-to/install-with-systemd.md and docs/how-to/install-with-docker.md.

Building from source

Requires Zig 0.16.0 and Node.js 24 (for the web UI). C dependencies (SQLite, mbedTLS) are vendored and built by zig build.

(cd admin && npm ci && npm run build)          # web UI -> admin/dist
zig build -Dadmin-dist=admin/dist                # native binary -> zig-out/bin/nxdns
zig build test --summary all                 # unit tests

The release artifacts come out of the same build graph, so the whole release build runs on a laptop exactly as it runs on the CI runner:

(cd admin && npm ci && npm run build)                # required: dist refuses the placeholder
VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
zig build dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
    -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe     # tarballs -> zig-out/dist/
zig build verify-dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
    -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe     # the release checks

The version comes from build.zig.zon because verify-dist asserts the two agree; a tag sets both.

That is not a claim that your tarball will hash the same as a published one. Nothing in this project measures whether two builds of the same commit on two different machines land on the same bytes, so no document here describes the build as reproducible. The gate that would settle it is a recorded deferral — specs/milestone-14.md ruling 12 — and docs/how-to/verify-a-release.md explains what a matching or differing hash is worth in the meantime.

Documentation

Start at docs/README.md, which splits the documentation into a tutorial, how-to guides, reference and explanation.

• docs/tutorial/first-run.md — build it, resolve a name, block a domain, on a scratch directory
• docs/how-to/install-with-systemd.md — a real install, including the Raspberry Pi 5
• docs/how-to/verify-a-release.md — checking the hashes and the signature before you install
• docs/reference/configuration.md — every configuration field
• docs/reference/api.md — REST API, auth and SSE
• docs/reference/cli.md — subcommands, flags and exit codes
• docs/explanation/architecture.md — module map and design
• PLAN.md and specs/ — scope, design decisions and per-milestone contracts

Licence

Copyright (c) 2026 Mokhtar Mial. nxdns is licensed under the European Union Public Licence v. 1.2 (EUPL-1.2); the full text is in LICENSE.

Every released tarball and image carries a THIRD-PARTY-NOTICES file assembled from the reviewed inventory in licenses/, which covers what the artifacts actually contain: musl, the Zig runtime, SQLite, Mbed TLS and its vendored Everest and p256-m code, and the JavaScript and CSS bundled into the admin UI.