indisoluble/a-healthy-dns repository overview

⁠A Healthy DNS

A Healthy DNS is a work-in-progress authoritative UDP DNS server for one hosted zone and optional alias zones. It serves ordinary static IPv4 A records, TCP-health-checked A records, or both in the same zone.

• A static entry is published without probing its IP addresses.
• A health-checked entry is published only while a TCP connection to its configured health port succeeds.

The server is intended for operators who need a small, startup-configured authoritative service whose in-memory answers follow backend reachability. It can run directly, as a Docker container, or as an AWS ECS Anywhere task on an external VM. It is not a recursive resolver or a general-purpose authoritative DNS implementation.

⁠Quick start with Docker

This local example uses UDP port 53053, so it does not require host port 53. The www record is static; checked demonstrates the health-checked configuration shape.

docker run -d \
  --name a-healthy-dns \
  -p 127.0.0.1:53053:53053/udp \
  indisoluble/a-healthy-dns \
  --port 53053 \
  --hosted-zone example.local \
  --zone-resolutions '{"www":["192.168.1.200"],"checked":{"ips":["192.168.1.100","192.168.1.101"],"health_port":8080}}' \
  --ns '["ns1.dns.example.net"]'

Verify the listener, authoritative apex, static answer, and logs:

docker ps --filter name=a-healthy-dns
dig @127.0.0.1 -p 53053 example.local SOA
dig @127.0.0.1 -p 53053 www.example.local A
docker logs --tail 50 a-healthy-dns

Static records become visible on the updater's first refresh. Repeat the A query if it races startup. The untagged image is suitable for this local example; production deployments should pin a version and apply the deployment guidance⁠.

⁠Quick start from source

Requires Python 3.11 or newer.

git clone https://github.com/indisoluble/a-healthy-dns.git
cd a-healthy-dns
python3 -m venv .venv
source .venv/bin/activate
pip install .

a-healthy-dns \
  --hosted-zone example.local \
  --zone-resolutions '{"www":["192.168.1.200"],"checked":{"ips":["192.168.1.100","192.168.1.101"],"health_port":8080}}' \
  --ns '["ns1.dns.example.net"]'

From another terminal, verify the foreground process:

dig @127.0.0.1 -p 53053 example.local SOA
dig @127.0.0.1 -p 53053 www.example.local A

⁠Behaviour at a glance

• The primary hosted zone and every configured alias zone expose the same active record state.
• The base zone contains generated SOA and NS data plus publishable IPv4 A records. Valid EDNS(0) requests receive a fixed 512-byte EDNS response envelope, but larger-payload negotiation and option-specific processing are not supported. IPv6 answers, recursion, transfers, and DNS-over-TCP remain outside scope.
• A background updater probes only health-checked IPs, treats static IPs as publishable, and atomically replaces the active zone when publication state changes.
• The query path reads a consistent zone version. Exact response codes, negative answers, malformed-packet handling, and RFC 8482 ANY minimization are defined in the RFC conformance contract⁠.
• Optional signing publishes generated DNSKEY, NSEC, and RRSIG artifacts. Full DNSSEC authoritative-server semantics are intentionally out of scope.
• Configuration is startup-only. SIGINT and SIGTERM stop the UDP service and background updater cleanly.

⁠Documentation

The returning-maintainer path is README -> Project brief⁠ -> Architecture⁠.