73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# 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
|