kdns

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2026 License: BSD-3-Clause

README

KDNS Logo

A high-performance authoritative DNS server written in Go from scratch.

Latest Release CI Status Go Report Card Go Reference Docker Hub License

Note on AI collaboration:
KDNS was built from scratch as an educational project to explore low-level networking, zero-allocation Go patterns, and distributed state—developed in close pair-programming collaboration with an AI coding agent.

Overview

KDNS is a lightweight, zero-dependency authoritative DNS server designed for fast responses, low memory usage, and simple operations.

       +-------------------------------------------------------------------+
       |                               KDNS                                |
       |                                                                   |
       |  +-------------------------------------------------------------+  |
       |  |                         Data Plane                          |  |
       |  |    UDP / TCP :5353       DoT :853       DoH :8443 (/query)  |  |
       |  +------------------------------+------------------------------+  |
       |                                 |                                 |
       |                            [Read Path]                            |
       |                                 v                                 |
       |  +-------------------------------------------------------------+  |
       |  |                      In-Memory Engine                       |  |
       |  |          Radix tree (routing)   +   Sharded LRU cache       |  |
       |  +------------------------------^------------------------------+  |
       |                                 |                                 |
       |                      [Mutations & Snapshots]                      |
       |                                 |                                 |
       |  +------------------------------v------------------------------+  |
       |  |                       Storage Engine                        |  |
       |  |    mutations.wal (Group Commit)  <->  state.snap (Deflate)  |  |
       |  +------------------------------^------------------------------+  |
       |                                 |                                 |
       |                         [Cluster & Mgmt]                          |
       |                                 |                                 |
       |  +------------------------------+------------------------------+  |
       |  |                    Control & Replication                    |  |
       |  |    REST API :8080        RFC 2136       Cluster :8081 (HA)  |  |
       |  +-------------------------------------------------------------+  |
       +-------------------------------------------------------------------+

Key highlights

  • Zero heap allocations on resolution: Reuses buffer pools and serves pre-packed wire payloads to keep the garbage collector out of the query hot path.
  • Reverse-label radix tree: Domains are indexed from right to left (. → com → example → www). Lookups take only 2 to 4 steps, with automatic wildcard fallbacks (*.example.com) and zone delegations.
  • Durability with WAL and compressed snapshots: Mutations are written sequentially to mutations.wal with CRC32 checksums. Periodic background compaction compresses the state into state.snap (-94% disk footprint).
  • Primary / replica streaming: Zero-dependency replication where replica nodes stream mutations over HTTP (:8081), writing to local disk and updating memory in a single pass.
  • DNSSEC, TSIG & rate limiting: On-the-fly RRSIG signing (ECDSA P-256 / Ed25519) with NSEC denial proofs when requested (DO=1), HMAC TSIG authentication for RFC 2136 dynamic updates, and response rate limiting (RRL).
  • Management API & metrics: REST endpoints on port 8080, RFC 1035 zone exporter, native Prometheus /metrics, and Kubernetes probes (/livez, /readyz, /startupz).

What KDNS is not (by design)

To keep things simple, fast, and maintainable, a few features are deliberately left out:

  • It is not a recursive resolver: KDNS only serves the zones you configure. It won't resolve arbitrary internet domains or act as a caching DNS forwarder for your home network.
  • It does not chase CNAMEs: Following the original RFC 1034 separation of concerns (like NSD and Knot DNS), KDNS returns the CNAME in the Answer section and lets the recursive resolver follow it.
  • No legacy AXFR/IXFR transfers: Zone replication between nodes uses authenticated HTTP streaming on port 8081 instead of plaintext transfers over port 53. If you need standard zone files, use the /v1/export/zonefile endpoint.
  • No plugins or scripting engines: KDNS compiles into a single, self-contained static binary without dynamic .so plugins or external scripting hooks.

Standards & RFC compliance

Standard / RFC Category Implementation & Details
RFC 1034 & 1035 Core DNS Binary wire parser/packer, pointer compression, multiline master zone file parser.
RFC 1034 §4.3.2 Zone cuts Radix tree interception returning delegation referrals (NOERROR, AA=0, Authority NS, glue in Additional).
RFC 2136 Dynamic updates Complete Opcode 5 UPDATE engine verifying 5 prerequisite rules and applying 4 update operations to WAL.
RFC 2308 Negative caching Authority section contains enclosing zone SOA with calculated MINIMUM TTL on NXDOMAIN and NODATA.
RFC 2845 & 8945 TSIG auth HMAC-SHA256, HMAC-SHA512, HMAC-SHA1, HMAC-MD5 with timing-attack resistant signature verification.
RFC 4034 & 4035 DNSSEC On-the-fly RRSIG signing (ECDSA P-256 / Ed25519), apex DNSKEY/DS, and windowed NSEC type bitmaps (DO=1).
RFC 4592 Wildcards Exact-match precedence over wildcards with proper Empty Non-Terminal (ENT) synthesis.
RFC 6891 EDNS0 Buffer size negotiation (capped at 1232 bytes), DO bit extraction, duplicate OPT rejection (FORMERR).
RFC 7766 TCP framing Length-prefixed asynchronous TCP pipelining supporting full 64KB message payloads.
RFC 7858 & 9539 DNS-over-TLS Native listener on port 853 with zero-downtime certificate hot-reloading (SIGHUP).
RFC 8484 DNS-over-HTTPS Dedicated listener on :8443 (GET base64url & POST) with dynamic Cache-Control: max-age=<TTL> headers.
RFC 8482 Minimal ANY Anti-DDoS defense: Rather than returning all records for TypeANY (255)—a common vector for 100x amplification attacks—KDNS returns a single minimal RRSet, neutralizing DDoS reflection exploits.
RFC 1035 §4.1.1 Anti-reflection Incoming packets with QR=1 (response bit set) are silently dropped to prevent reflection loops.
BCP 140 / RRL Rate limiting Token bucket rate limiting with subnet aggregation (/24 IPv4, /56 IPv6) and SLIP (TC=1) truncation.

Network & port topology

Port Protocol Plane Description
5353 UDP / TCP Data Authoritative DNS query resolution (RFC 1034 / 1035) and RFC 2136 dynamic updates.
853 TCP (TLS) Data DNS-over-TLS (DoT, RFC 7858) with zero-downtime certificate hot-reloading (SIGHUP).
8443 HTTP / TLS Data Dedicated DNS-over-HTTPS (DoH, RFC 8484) endpoint on /dns-query and health probes.
8080 HTTP Control Management REST API (/v1/records), zone exporter, and Prometheus /metrics.
8081 HTTP / TLS Cluster Primary / replica asynchronous WAL streaming (/v1/cluster/stream) and snapshot sync.

Supported platforms

Platform Architectures Packages
Linux amd64, arm64 Standalone archive (.tar.gz) & Distroless OCI container
FreeBSD amd64, arm64 Standalone archive (.tar.gz)
OpenBSD amd64, arm64 Standalone archive (.tar.gz)
NetBSD amd64, arm64 Standalone archive (.tar.gz)

Quick start

Run with Docker

docker run -d \
  --name kdns \
  -p 5353:5353/udp \
  -p 5353:5353/tcp \
  -p 8443:8443/tcp \
  -p 8080:8080/tcp \
  -e KDNS_API_TOKEN="supersecrettoken12345" \
  -v kdns_data:/data \
  aoliveti/kdns:latest

Build from source

Requires Go 1.27+:

git clone https://github.com/aoliveti/kdns.git
cd kdns

# Build static binary into bin/kdns
make build

# Start standalone daemon
./bin/kdns \
  --address :5353 \
  --http-addr :8080 \
  --api-token "supersecrettoken12345" \
  --storage-dir ./data

Operational examples

1. Insert a DNS record via REST API

curl -X PUT http://127.0.0.1:8080/v1/records/app.example.com \
  -H "Authorization: Bearer supersecrettoken12345" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "type": "A",
        "ttl": 300,
        "rdata": ["192.0.2.1"]
      }
    ]
  }'

2. Query the server

dig @127.0.0.1 -p 5353 app.example.com A +short
# Output: 192.0.2.1

3. Check health probes

curl -i http://127.0.0.1:8443/livez
# HTTP/1.1 200 OK
# ok

Documentation & API specifications

Detailed architectural deep dives, implementation guides, and API contracts are available in docs/ and api/:

Guide Subsystem Topics Covered
Architecture & Design System Design CQRS concurrency model, physical port isolation (:5353, :853, :8443, :8080, :8081), zero-allocation data plane pipeline, POSIX signal handling (SIGHUP/SIGTERM).
REST API Reference Control Plane Endpoints (/v1/records, /search), streaming zone file export (/v1/export/zonefile), Kubernetes probes (/livez, /readyz, /startupz), Prometheus /metrics.
OpenAPI 3.0 Spec API Contracts Formal OpenAPI 3.0 specification for management and cluster replication endpoints.
Clustering & HA High Availability Primary / replica asynchronous WAL streaming (:8081), real-time dual disk/memory ingestion, safe atomic state replacement on compaction, read-only replica mode.
Storage & WAL Internals Persistence Group-commit write batching, big-endian binary framing, Deflate compressed snapshots (state.snap, -94%), atomic compaction guardrails.
Radix Tree Implementation Routing Engine Reverse-label domain hierarchy, Copy-on-Write concurrency (100% lock-free reads), RFC 4592 wildcard synthesis, ENT suppression, CNAME transparency.
DNSSEC & TSIG Security Cryptography On-the-fly RRSIG signing (ECDSA P-256 / Ed25519) on DO=1, windowed NSEC denial bitmaps, apex DNSKEY/DS generation, TSIG transaction authentication.
Transports & Protocols Networking UDP/TCP length-prefixed pipelining, DoT on :853, DoH on :8443 with dynamic Cache-Control, BCP 140 Response Rate Limiting (RRL), CHAOS diagnostics.

Engineering standards & verification

# Run test suite with race detector (24 packages, 0 data races)
go test -race -count=1 ./...

# Run strict linter suite (29 linters strictly enforced)
golangci-lint run ./...

# Run benchmark suite
go test -bench=. -benchmem ./...

# Run fuzz testing battery (100k iterations per target)
make fuzz

Contributing & Security

License

KDNS is open-source software licensed under the BSD 3-Clause License.

Directories

Path Synopsis
cmd
kdns command
Package main provides the entrypoint for the kdns server.
 Package main provides the entrypoint for the kdns server.
internal
api
Package api provides the control-plane HTTP REST API and telemetry exporter.
 Package api provides the control-plane HTTP REST API and telemetry exporter.
cache
Package cache provides a highly concurrent, sharded LRU-TTL memory store optimized for high-throughput authoritative DNS query resolution.
 Package cache provides a highly concurrent, sharded LRU-TTL memory store optimized for high-throughput authoritative DNS query resolution.
cluster/hub
Package hub implements the Primary node replication HTTP streaming server for KDNS.
 Package hub implements the Primary node replication HTTP streaming server for KDNS.
cluster/replica
Package replica implements the read-only Replica node synchronization client for KDNS.
 Package replica implements the read-only Replica node synchronization client for KDNS.
codec
Package codec provides binary stream encoding and decoding for DNS records utilized in Write-Ahead Log (WAL) persistence journals and memory state snapshots.
 Package codec provides binary stream encoding and decoding for DNS records utilized in Write-Ahead Log (WAL) persistence journals and memory state snapshots.
daemon
Package daemon orchestrates the lifecycle, services, and execution runtime of kdns.
 Package daemon orchestrates the lifecycle, services, and execution runtime of kdns.
dns
dnssec
Package dnssec implements cryptographic DNSSEC signing on-the-fly, NSEC denial of existence generation, and key management (RFC 4033, 4034, 4035, 5155, 6605, 8080).
 Package dnssec implements cryptographic DNSSEC signing on-the-fly, NSEC denial of existence generation, and key management (RFC 4033, 4034, 4035, 5155, 6605, 8080).
dnsserver
Package dnsserver implements the high-performance DNS Data Plane server, handling UDP, TCP, and DoT connections, connection lifecycles, and protocol limits on port 53 and 853.
 Package dnsserver implements the high-performance DNS Data Plane server, handling UDP, TCP, and DoT connections, connection lifecycles, and protocol limits on port 53 and 853.
doh
Package doh implements a zero-allocation, RFC 8484 compliant DNS-over-HTTPS (DoH) server.
 Package doh implements a zero-allocation, RFC 8484 compliant DNS-over-HTTPS (DoH) server.
metrics
Package metrics implements zero-allocation, lock-free telemetry collection and native Prometheus text format exposition for kdns.
 Package metrics implements zero-allocation, lock-free telemetry collection and native Prometheus text format exposition for kdns.
radix
Package radix implements an O(k) radix tree optimized for DNS domain lookups.
 Package radix implements an O(k) radix tree optimized for DNS domain lookups.
rfc2136
Package rfc2136 implements Dynamic DNS Updates parsing, prerequisite evaluation, and atomic batch application in accordance with RFC 2136.
 Package rfc2136 implements Dynamic DNS Updates parsing, prerequisite evaluation, and atomic batch application in accordance with RFC 2136.
rrl
Package rrl implements high-performance, zero-allocation Response Rate Limiting (RRL) for authoritative DNS servers in accordance with BCP 140 specifications.
 Package rrl implements high-performance, zero-allocation Response Rate Limiting (RRL) for authoritative DNS servers in accordance with BCP 140 specifications.
snapshot
Package snapshot manages CRC32-verified state snapshots for persistent storage.
 Package snapshot manages CRC32-verified state snapshots for persistent storage.
state
Package state provides the in-memory Radix tree state and LRU query resolution view.
 Package state provides the in-memory Radix tree state and LRU query resolution view.
store
Package store implements high-throughput persistence, WAL group-commit batching, and snapshots.
 Package store implements high-throughput persistence, WAL group-commit batching, and snapshots.
tlsreload
Package tlsreload provides lock-free hot-reloading capabilities for TLS certificates.
 Package tlsreload provides lock-free hot-reloading capabilities for TLS certificates.
tsig
Package tsig implements Transaction Signatures for DNS authentication (RFC 2845 and RFC 8945).
 Package tsig implements Transaction Signatures for DNS authentication (RFC 2845 and RFC 8945).
wal
Package wal provides Write-Ahead Log appending and replay mechanisms for crash safety.
 Package wal provides Write-Ahead Log appending and replay mechanisms for crash safety.
zone
Package zone provides a high-performance, RFC 1035 compliant parser for DNS master zone files.
 Package zone provides a high-performance, RFC 1035 compliant parser for DNS master zone files.
test
integration

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.