A DNS server with a TUI and REST API. For common record types (A, AAAA, MX, …) answers come from local records, then cache (if enabled), then upstreams queried in parallel; the first successful upstream wins. PTR uses local data (including PTR synthesized from A) first, then the same path on miss.
| Doc | What it covers |
|---|---|
| docs/resolution.md | Resolution behavior: local/cache/upstream order, adblock and whitelist interaction, cache warm/compaction, mermaid flow diagram. |
| docs/usage.md | Server and client commands, flags, config/data paths, TUI overview, demo. |
| docs/config-files.md | JSON files (dnsrecords, dnsservers, cache, dnsplane.json), records source (file/URL/Git), domain whitelist, adblock, main config tables, REST API, curl (upstream health). |
| docs/logging.md | Log directory, severity, rotation; client --log-file. |
| docs/systemd.md | systemd install using systemd/dnsplane.service. |
| docs/host-tuning.md | Optional Linux OS / host tuning for DNS latency (buffers, limits, containers). |
| docs/upstream-health.md | Upstream health checks: probes, marking servers down, config, logs, curl. |
| docs/clustering.md | Multi-node record sync: TCP peers, cluster_* keys, auth, deployment notes. |
| docs/security-public-dns.md | DoT / DoH / DNSSEC when exposing DNS to the internet. |
| docs/dnsplane.example.json | Full annotated example dnsplane.json. |
| examples/dnsplane-example.json | Short starter config (DoT/DoH/DNSSEC present, off by default). |
| examples/dnsservers-example.json | Example dnsservers.json with domain_whitelist. |
| examples/curl-stats-dashboard.sh | curl examples for dashboard endpoints. |
| examples/README.md | Index of example files vs docs/dnsplane.example.json. |
| TODO.md | Upcoming work. |
DoT, DoH, and DNSSEC are also summarized in the main config tables in config-files.md.
- Adblock: Load lists from file or URL; merge multiple sources; optional
adblock_list_filesin config. - Full stats: Optional persistent stats DB and TUI
statisticscommands (full_stats,full_stats_dir). - Split DNS: Per-upstream
domain_whitelistindnsservers.json/ TUI. - Records from URL or Git: Read-only remote sources with a refresh interval.
- TUI server control:
server config/set/save, and start/stop for DNS, API, and client listeners.
Recent releases add graceful shutdown timeouts for systemd, statistics in the TUI when full_stats is enabled, and build metadata (version, Go, OS, arch) on stats and health endpoints.
Contributions are welcome. Please follow the Google Go Style Guide. Commits use the Developer Certificate of Origin (DCO)—see CONTRIBUTING.md for sign-off. Roles and decisions are described in GOVERNANCE.md.
Licensed under GPL-2.0-only.
