sdns

command module
v1.5.3 Latest Latest
Warning

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

Go to latest
Published: Jun 8, 2025 License: MIT Imports: 29 Imported by: 0

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 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

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

Directories

Path Synopsis
Package cache provides DNS caching functionality for SDNS.
Package cache provides DNS caching functionality for SDNS.
hostsfile
Package hostsfile implements a high-performance hosts file resolver with advanced features like wildcard support and automatic reloading
Package hostsfile implements a high-performance hosts file resolver with advanced features like wildcard support and automatic reloading
doh
doq
Package util provides DNS protocol utilities for SDNS.
Package util provides DNS protocol utilities for SDNS.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL