sdns

README

SDNS :rocket:

A high-performance, recursive DNS resolver server with DNSSEC support, focused on preserving privacy.

---

Installation

Install SDNS using the go install command:

go install github.com/semihalev/sdns@latest

Pre-built Binaries

Download the latest release from the GitHub Releases page.

Docker

• Docker Package (updated every release)
• Docker Hub (alternative)

$ docker run -d --name sdns -p 53:53 -p 53:53/udp sdns

Docker Compose

Install docker-compose and run from the root directory:

$ sudo apt install docker-compose
$ docker-compose up -d

Homebrew for macOS

Install and run as a service:

$ brew install sdns
$ brew install semihalev/tap/sdns (updated every release)
$ brew services start sdns

Snapcraft

$ snap install sdns

AUR for ArchLinux

$ yay -S sdns-git

Note: Pre-built binaries, Docker packages, brew taps, and snaps are automatically created by GitHub workflows.

Building from Source

$ go build

Testing

$ make test

Flags

Flag	Description
-c, --config PATH	Location of the config file. If it doesn't exist, a new one will be generated
-v, --version	Show the SDNS version
-h, --help	Show help information and exit

Debugging Environment

To debug your environment, execute the following command:

$ export SDNS_DEBUGNS=true && export SDNS_PPROF=true && ./sdns

The SDNS_DEBUGNS environment variable is beneficial for verifying the RTT (Round Trip Time) of authoritative servers. To use it, send an HINFO query for zones with chaos class.

Here's an example of the output you might receive:

$ dig chaos hinfo example.com

; <<>> DiG 9.17.1 <<>> chaos hinfo example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 29636
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 4, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: f27dbb995df5ac79e4fa37c07d131b5bd03aa1c5f802047a7c02fb228a886cb281ecc319323dea81 (good)
;; QUESTION SECTION:
;example.com.			CH	HINFO

;; AUTHORITY SECTION:
example.com.		0	CH	HINFO	"Host" "IPv4:199.43.135.53:53 rtt:142ms health:[GOOD]"
example.com.		0	CH	HINFO	"Host" "IPv4:199.43.133.53:53 rtt:145ms health:[GOOD]"
example.com.		0	CH	HINFO	"Host" "IPv6:[2001:500:8f::53]:53 rtt:147ms health:[GOOD]"
example.com.		0	CH	HINFO	"Host" "IPv6:[2001:500:8d::53]:53 rtt:148ms health:[GOOD]"

Configuration (v1.5.2)

Key	Description
version	Configuration file version
directory	Working directory for SDNS data storage. Must be writable by the SDNS process. Default: "db"
bind	DNS server binding address and port. Default: ":53"
bindtls	DNS-over-TLS (DoT) server binding address. Default: ":853"
binddoh	DNS-over-HTTPS (DoH) server binding address. Default: ":8053"
binddoq	DNS-over-QUIC (DoQ) server binding address. Default: ":853"
tlscertificate	Path to the TLS certificate file for DoT/DoH/DoQ
tlsprivatekey	Path to the TLS private key file for DoT/DoH/DoQ
outboundips	Outbound IPv4 addresses for DNS queries. Multiple addresses enable random source IP selection per request
outboundip6s	Outbound IPv6 addresses for DNS queries. Multiple addresses enable random source IP selection per request
rootservers	Root DNS servers (IPv4). These are the authoritative name servers for the DNS root zone
root6servers	Root DNS servers (IPv6). These are the authoritative name servers for the DNS root zone
dnssec	Enable DNSSEC validation for secure DNS responses. Options: "on" or "off". Default: "on"
rootkeys	DNSSEC root zone trust anchors in DNSKEY format
fallbackservers	Upstream DNS servers used when all others fail. Format: "IP:port" (e.g., "8.8.8.8:53")
forwarderservers	Forward all queries to these DNS servers. Format: "IP:port" (e.g., "8.8.8.8:53")
api	HTTP API server binding address for statistics and control. Leave empty to disable
bearertoken	API bearer token for authorization. If set, Authorization header must be included in API requests
blocklists	URLs of remote blocklists to download and use for filtering
blocklistdir	[DEPRECATED] Blocklist directory. Now automatically created in the working directory
loglevel	Logging verbosity level. Options: crit, error, warn, info, debug. Default: "info"
accesslog	Path to the access log file in Common Log Format. Leave empty to disable
nullroute	IPv4 address returned for blocked A queries. Default: "0.0.0.0"
nullroutev6	IPv6 address returned for blocked AAAA queries. Default: "::0"
accesslist	IP addresses/subnets allowed to make queries. Default allows all: ["0.0.0.0/0", "::0/0"]
querytimeout	Maximum time to wait for any DNS query to complete. Default: "10s"
timeout	Network timeout for upstream DNS queries. Default: "2s"
hostsfile	Path to hosts file (RFC 952/1123 format) for local resolution. Leave empty to disable
expire	Cache TTL for error responses in seconds. Default: 600
cachesize	Maximum number of cached DNS records. Default: 256000
prefetch	Prefetch threshold percentage (10-90). Refreshes popular cache entries before expiration. 0 disables
maxdepth	Maximum recursion depth for queries. Prevents infinite loops. Default: 30
ratelimit	Global query rate limit per second. 0 disables. Default: 0
clientratelimit	Per-client rate limit per minute. 0 disables. Default: 0
domainmetrics	Enable per-domain query metrics collection. Default: false
domainmetricslimit	Maximum number of domains to track in metrics. 0 = unlimited (use with caution). Default: 10000
blocklist	Manual domain blocklist. Domains listed here will be blocked
whitelist	Manual domain whitelist. Overrides blocklist matches
cookiesecret	DNS cookie secret (RFC 7873) for client verification. Auto-generated if not set
nsid	DNS server identifier (RFC 5001) for identifying this instance. Leave empty to disable
chaos	Enable responses to version.bind and hostname.bind chaos queries. Default: true
qname_min_level	QNAME minimization level (RFC 7816). 0 disables. Higher values increase privacy but may impact performance
emptyzones	Enable local authoritative responses for RFC 1918 zones. See http://as112.net/ for details
tcpkeepalive	Enable TCP connection pooling for root and TLD servers. Improves performance by reusing connections. Default: false
roottcptimeout	TCP idle timeout for root server connections. Default: "5s"
tldtcptimeout	TCP idle timeout for TLD server connections (com, net, org, etc.). Default: "10s"
tcpmaxconnections	Maximum number of pooled TCP connections. 0 uses default. Default: 100
dnstapsocket	Unix domain socket path for dnstap binary DNS logging. Leave empty to disable
dnstapidentity	Server identity string for dnstap messages. Defaults to hostname
dnstapversion	Server version string for dnstap messages. Default: "sdns"
dnstaplogqueries	Log DNS queries via dnstap. Default: true
dnstaplogresponses	Log DNS responses via dnstap. Default: true
dnstapflushinterval	Dnstap message flush interval in seconds. Default: 5

Plugin Configuration

SDNS supports custom plugins to extend its functionality. The execution order of plugins and middlewares affects their behavior. Configuration keys must be strings, while values can be any type. Plugins are loaded before the cache middleware in the order specified.

For implementation details, see the example plugin.

Example Configuration

[plugins]
     [plugins.example]
     path = "/path/to/exampleplugin.so"
     config = {key_1 = "value_1", intkey = 2, boolkey = true, keyN = "nnn"}
     [plugins.another]
     path = "/path/to/anotherplugin.so"

Server Configuration Checklist

• Increase the file descriptor limit on your server

Features

• Linux/BSD/Darwin/Windows support
• Full DNS RFC compatibility
• DNS queries using both IPv4 and IPv6 authoritative servers
• High-performance DNS caching with prefetch support
• Full DNSSEC validation support with RFC 8914 Extended DNS Errors (EDE)
• DNS over TLS (DoT) support
• DNS over HTTPS (DoH) support with HTTP/3
• DNS over QUIC (DoQ) support
• Multiple outbound IP selection for queries
• Extensible middleware architecture
• RTT-based server prioritization with adaptive timeouts
• Parallel DNS lookups for improved performance
• Failover to backup servers on failure
• DNS forwarding support
• EDNS Cookie support (RFC 7873)
• EDNS NSID support (RFC 5001)
• Extended DNS Errors (EDE) support (RFC 8914)
• Full IPv6 support (both client and server communication)
• Query-based rate limiting
• Client IP-based rate limiting
• IP-based access control lists
• Comprehensive access logging
• Prometheus metrics with optional per-domain tracking
• DNS sinkholing for malicious domains
• HTTP API for management and statistics
• Cache purge via API and DNS queries
• Chaos TXT query support for version.bind and hostname.bind
• Empty zones support (RFC 1918)
• External plugin support
• Binary DNS logging via dnstap protocol (RFC 6742)
• QNAME minimization for privacy (RFC 7816)
• Automatic DNSSEC trust anchor updates (RFC 5011)
• Zero-allocation cache operations for improved performance
• TCP connection pooling for persistent connections

TODO

• [x] More tests
• [x] Try lookup NS address better way
• [x] DNS over TLS support
• [x] DNS over HTTPS support
• [x] Full DNSSEC support
• [x] RTT optimization
• [x] Access list
• [x] Periodic priming queries described at RFC 8109
• [x] Full IPv6 support (server<->server communication)
• [x] Query name minimization to improve privacy described at RFC 7816
• [x] DNAME Redirection in the DNS described at RFC 6672
• [x] Automated Updates DNSSEC Trust Anchors described at RFC 5011
• [ ] DNS64 DNS Extensions for NAT from IPv6 Clients to IPv4 Servers described at RFC 6147
• [x] DNS over QUIC support described at RFC 9250

Performance

Benchmark Environment

• Server Specifications:
  • Processor: Apple M1 Pro
  • Memory: 16GB

Benchmarking Tool

• Tool: DNS-OARC dnsperf
• Configuration:
  • Query volume: 50,000 sample queries
  • Test date: June 2025

Benchmark Comparisons

Tests were performed on the following DNS resolvers: SDNS 1.5.1, PowerDNS Recursor 5.0.2, BIND 9.19.12, and Unbound 1.17.1.

Benchmark Results

Resolver	Version	QPS	Avg Latency	Lost Queries	Runtime	Response Codes
SDNS	1.5.1	712/s	136ms	2 (0.004%)	70.2s	NOERROR: 67.82%, SERVFAIL: 1.64%, NXDOMAIN: 30.55%
PowerDNS	5.0.2	578/s	156ms	20 (0.04%)	86.5s	NOERROR: 67.64%, SERVFAIL: 1.92%, NXDOMAIN: 30.43%
BIND	9.19.12	405/s	200ms	156 (0.31%)	123.0s	NOERROR: 67.84%, SERVFAIL: 1.62%, NXDOMAIN: 30.54%
Unbound	1.17.1	338/s	237ms	263 (0.53%)	147.0s	NOERROR: 68.20%, SERVFAIL: 1.20%, NXDOMAIN: 30.60%

Performance Summary

SDNS demonstrates superior performance across all key metrics:

• Highest throughput: 712 queries per second (23% faster than PowerDNS, 76% faster than BIND, 111% faster than Unbound)
• Lowest latency: 136ms average (13-43% lower than competitors)
• Best reliability: Only 2 lost queries out of 50,000 (99.996% success rate)
• Fastest completion: 70.2 seconds total runtime

Contributing

We welcome pull requests. If you're considering significant changes, please start a discussion by opening an issue first.

Before submitting patches, please review our CONTRIBUTING guidelines.

♥ Made With

• miekg/dns - Alternative (more granular) approach to a DNS library

Inspired by

• looterz/grimd

License

MIT

Documentation

Overview

Package main implements SDNS - a high-performance, recursive DNS resolver server with DNSSEC support.

SDNS is a privacy-focused DNS server that provides:

• High-performance recursive DNS resolution with aggressive caching
• Full DNSSEC validation and verification support
• DNS-over-HTTPS (DoH) and DNS-over-QUIC (DoQ) protocols
• Privacy-preserving features including query minimization (RFC 7816)
• Flexible middleware architecture for extending functionality
• Built-in blocklist and allowlist support
• Rate limiting and access control
• Metrics and monitoring via Prometheus
• Automatic root trust anchor updates (RFC 5011)

Architecture:

SDNS uses a middleware-based architecture where each component processes DNS queries in a chain. The middleware order is important and defined as:

1. Recovery - Panic recovery and error handling
2. Loop - Detection and prevention of query loops
3. Metrics - Prometheus metrics collection with optional per-domain tracking
4. Dnstap - Binary DNS message logging (dnstap format)
5. AccessList - IP-based access control
6. RateLimit - Query rate limiting per client
7. EDNS - EDNS0 support and processing
8. AccessLog - Query logging
9. Chaos - Chaos TXT query responses
10. HostsFile - Local hosts file resolution
11. BlockList - Domain blocking with pattern matching
12. AS112 - RFC 7534 AS112 redirection
13. Cache - High-performance query caching
14. Failover - Upstream server failover
15. Resolver - Recursive DNS resolution with DNSSEC
16. Forwarder - Forward queries to upstream servers

Configuration:

SDNS uses a configuration file (default: sdns.conf) that supports:

• Server binding addresses for DNS, DoH, and DoQ
• TLS certificate configuration
• Middleware-specific settings
• Upstream resolver configuration
• Cache size and TTL settings
• Logging levels and output

Usage:

sdns [flags]
sdns [command]

Available Commands:

help        Help about any command
version     Print version information

Flags:

-c, --config string   Location of config file (default "sdns.conf")
-h, --help           Help for sdns

Example:

# Start with default config
sdns

# Start with custom config
sdns -c /etc/sdns/sdns.conf

# Show version
sdns version

For more information, visit https://sdns.dev