RouteDNS is a composable DNS stub resolver, proxy and router written in Go. It enables building flexible DNS processing pipelines with support for all modern DNS protocols, query routing, caching, blocklists, DNSSEC validation, Lua scripting, and 30+ other pipeline components — all configured via TOML.
graph LR
C[Clients] --> L
subgraph RouteDNS
L[Listeners<br/>DNS · DoT · DoH<br/>DoQ · DTLS · ODoH] --> P[Routers / Groups / Modifiers<br/>Router · Cache · Blocklist<br/>Rate Limiter · Load Balancer<br/>DNSSEC Validator · Lua Script<br/>...30+ types]
P --> R[Resolvers<br/>DNS · DoT · DoH<br/>DoQ · DTLS · ODoH]
end
R --> U[Upstream DNS]
classDef ext fill:#e2e8f0,stroke:#64748b,color:#1e293b
classDef listen fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
classDef proc fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef resolve fill:#d1fae5,stroke:#10b981,color:#064e3b
class C,U ext
class L listen
class P proc
class R resolve
Listeners receive queries over any supported protocol. Routers, groups and modifiers form the processing pipeline — routing, filtering, caching, and transforming queries and responses. Resolvers forward queries upstream. Every component implements the same Resolver interface, so they can be composed freely.
Protocols
- Plain DNS over UDP and TCP, with connection reuse and pipelining
- DNS-over-TLS (DoT, RFC 7858) — client and server
- DNS-over-HTTPS (DoH, RFC 8484) — client and server with HTTP/2
- DNS-over-QUIC (DoQ, RFC 9250) — client and server, with 0-RTT support
- DNS-over-DTLS (RFC 8094) — client and server
- DNS-over-HTTPS with QUIC transport — client and server
- Oblivious DoH (ODoH, RFC 9230) — client, proxy and target
- Custom CAs and mutual TLS (mTLS)
- SOCKS5 proxy support
Query Processing
- DNSSEC validation with IANA trust anchor support
- Blocklists — domain, regex, hosts-file, wildcard formats with auto-refresh from HTTP/file sources
- Response blocklists — filter by response name, IP/CIDR, GeoIP country, or ASN
- MAC address filtering via EDNS0
- Lua scripting with sandboxed execution for custom query handling logic
- Query/response modification and name translation
- Static responses using Go templates
- EDNS0 Client Subnet (ECS) manipulation (RFC 7871)
- EDNS0 query and response padding (RFC 7830, RFC 8467)
Routing
- Route by query name (regex), query type, query class, source IP/CIDR, or EDNS Client Subnet
- Time-of-day based routing
- Multiple routes evaluated in order — first match wins
Resilience & Performance
- Caching with memory or Redis backend, negative-TTL support, and prefetch
- TTL manipulation (min/max clamping)
- Multiple load-balancing algorithms: round-robin, fail-rotate, fastest, random
- Request deduplication
- Rate limiting per client subnet
- Truncate-retry (automatic TCP fallback on truncated UDP responses)
- Bootstrap addresses to avoid initial service name lookups
Deployment
- Linux network namespace support — listen in one netns, resolve in another
- Firewall mark (fwmark) and interface binding (SO_BINDTODEVICE) for policy routing and VRF
- Admin listener with expvar metrics (Prometheus-compatible)
- Query/response logging, syslog integration
- Platform independent — written in Go
Requires Go 1.24+:
go install github.com/folbricht/routedns/cmd/routedns@latest
Or build from source:
git clone https://github.com/folbricht/routedns.git
cd routedns/cmd/routedns && go install
Pre-built binaries for Linux (amd64, arm64, armv7), macOS (amd64, arm64), FreeBSD, and Windows are available on the GitHub Releases page.
A container is available on Docker Hub:
docker run -d --rm --network host folbricht/routedns
With a custom config:
docker run -d --rm --network host -v /path/to/config.toml:/config.toml folbricht/routedns
This minimal config forwards all local DNS queries encrypted via DNS-over-TLS to Cloudflare, with caching. Set your system's nameserver to 127.0.0.1 (e.g. in /etc/resolv.conf).
[resolvers.cloudflare-dot]
address = "1.1.1.1:853"
protocol = "dot"
[groups.cloudflare-cached]
type = "cache"
resolvers = ["cloudflare-dot"]
backend = {type = "memory"}
[listeners.local-udp]
address = "127.0.0.1:53"
protocol = "udp"
resolver = "cloudflare-cached"
[listeners.local-tcp]
address = "127.0.0.1:53"
protocol = "tcp"
resolver = "cloudflare-cached"Save as config.toml and run:
routedns config.toml
An example systemd service file is provided here.
Route internal queries to company DNS servers while sending everything else securely to Cloudflare via DoH. Company servers are grouped with fail-rotate for resilience.
graph LR
C[Client] --> L[Listener<br/>UDP/TCP :53]
L --> RT[Router]
RT -->|*.mycompany.com| CO[Fail-Rotate<br/>Company DNS A/B]
RT -->|everything else| CF[Cloudflare DoH]
classDef ext fill:#e2e8f0,stroke:#64748b,color:#1e293b
classDef listen fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
classDef proc fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef resolve fill:#d1fae5,stroke:#10b981,color:#064e3b
class C ext
class L listen
class RT proc
class CO,CF resolve
Configuration: use-case-2.toml
Single out devices by IP address and apply a custom blocklist plus a filtered upstream resolver, while giving all other devices unfiltered access.
graph LR
C[Client] --> L[Listener<br/>UDP/TCP :53]
L --> RT[Router]
RT -->|source 192.168.1.123| BL[Blocklist] --> CB[CleanBrowsing DoT]
RT -->|default| CF[Cloudflare DoT]
classDef ext fill:#e2e8f0,stroke:#64748b,color:#1e293b
classDef listen fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
classDef proc fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef resolve fill:#d1fae5,stroke:#10b981,color:#064e3b
class C ext
class L listen
class RT,BL proc
class CB,CF resolve
Configuration: family-browsing.toml
Protect the whole network with multi-layer blocklists (query names, response names, response IPs), caching, and TTL clamping. Blocklists auto-refresh daily from remote HTTP sources.
graph LR
C[Clients] --> L[Listener<br/>UDP/TCP :53]
L --> CA[Cache]
CA --> TTL[TTL Modifier]
TTL --> BQ[Query Blocklist]
BQ --> BR[Response Name<br/>Blocklist]
BR --> BI[Response IP<br/>Blocklist]
BI --> CF[Cloudflare DoT<br/>Fail-Rotate]
classDef ext fill:#e2e8f0,stroke:#64748b,color:#1e293b
classDef listen fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
classDef proc fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef resolve fill:#d1fae5,stroke:#10b981,color:#064e3b
class C ext
class L listen
class CA,TTL,BQ,BR,BI proc
class CF resolve
Configuration: use-case-6.toml
Validate DNSSEC signatures on all responses using built-in root trust anchors. Queries with invalid signatures are rejected.
graph LR
C[Client] --> L[Listener<br/>UDP/TCP :53]
L --> DV[DNSSEC Validator<br/>IANA Trust Anchor]
DV --> CF[Cloudflare DoT]
classDef ext fill:#e2e8f0,stroke:#64748b,color:#1e293b
classDef listen fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
classDef proc fill:#fef3c7,stroke:#f59e0b,color:#78350f
classDef resolve fill:#d1fae5,stroke:#10b981,color:#064e3b
class C ext
class L listen
class DV proc
class CF resolve
[resolvers.cloudflare-dot]
address = "1.1.1.1:853"
protocol = "dot"
[groups.dnssec-validated]
type = "dnssec-validator"
resolvers = ["cloudflare-dot"]
[listeners.local-udp]
address = "127.0.0.1:53"
protocol = "udp"
resolver = "dnssec-validated"
[listeners.local-tcp]
address = "127.0.0.1:53"
protocol = "tcp"
resolver = "dnssec-validated"- Configuration Guide — full reference for all component types and options
- Example Configs — ready-to-use configuration files