dnsproxy
A fast, robust, and resilient DNS proxy server written in Rust.
Features
- Multi-Protocol Client Support: Concurrent UDP and TCP DNS listeners (RFC 1035 / RFC 7766) on configurable IP addresses and ports.
- Upstream Forwarding Strategies:
parallel: Queries all configured upstreams concurrently, returning the fastest valid response.round_robin/load_balance: Sequential failover rotating through upstream servers.
- DNS-over-HTTPS (DoH): Native RFC 8484 DoH query support with persistent HTTP connection pooling (
reqwest) and keep-alive optimization. - Per-Upstream SOCKS5 Proxying: Route individual DoH upstreams through separate SOCKS5 proxies with optional username and password authentication.
- Plain UDP DNS Support: Resolve domain names or IP-based upstreams directly or using a bootstrap resolver.
- Dual-Layer Caching:
- In-memory
(Name, RecordType)cache respecting DNS record TTLs. - Size-based LRU/expiry pruning (
max_cache_size,max_cache_ttl). - Atomic disk persistence across server restarts using atomic temporary files.
- In-memory
- IPv6 (AAAA) Filtering: Optional stripping of AAAA records with wildcard-enabled domain whitelist (
*.example.com). - Concurrency Rate Limiting: Semaphore-based concurrency limiter to prevent server overload.
- Modern Rust & Ergonomics: Built on Rust Edition 2024, fully modularized codebase, comprehensive unit test suite, and clean
clippyvalidation.
Quick Start with Cargo
1. Install Binary (dnsproxy)
This installs the dnsproxy binary into $HOME/.cargo/bin/.
2. Run
# Run with default config.toml
# Or run specifying a custom configuration file
3. Test DNS Resolution
# Query via UDP
# Query via TCP
Dependency Migration
All dependencies have been migrated from unreleased internal workspace versions to the latest published releases on crates.io:
| Dependency | Original Branch | dnsproxy (Latest) |
Notes |
|---|---|---|---|
hickory-proto |
0.27.0-alpha.1 (local) |
0.26.3 |
Core DNS protocol parsing & encoding |
hickory-resolver |
0.27.0-alpha.1 (local) |
0.26.3 |
Bootstrap resolver for upstream hostnames |
hickory-net |
0.27.0-alpha.1 (local) |
0.26.3 |
Async networking primitives |
tokio |
1.36 |
1.53.2 |
Async runtime (rt-multi-thread, net, sync) |
reqwest |
0.13.1 |
0.13.5 |
HTTP client with rustls and socks features |
clap |
4.0 |
4.6.7 |
CLI argument parsing with derive |
serde |
1.0 |
1.0.229 |
Configuration & cache serialization |
toml |
1.0.1 |
1.1.6 |
TOML configuration & persistent disk cache |
tracing / tracing-subscriber |
0.1.30 / 0.3.10 |
0.1.44 / 0.3.23 |
Structured logging with dynamic log level filtering |
futures-util |
0.3.5 |
0.3.34 |
Async combinators (select_all) |
Configuration
dnsproxy reads configuration from a TOML file (config.toml by default, or specified via --config / -c).
# Log level: trace, debug, info, warn, error
= "info"
# DNS Bootstrap resolvers for resolving upstream domains
= [
"1.1.1.1",
"9.9.9.9",
"8.8.8.8:53"
]
# Listen addresses & ports
= ["127.0.0.1"]
= [53000]
# Upstream resolution strategy: "parallel" or "round_robin"
= "parallel"
# Upstream query timeout
= "10s"
# Configured upstream servers
= [
"https://1.1.1.1/dns-query",
"https://9.9.9.9/dns-query",
# Route through a SOCKS5 proxy:
# { url = "https://8.8.4.4/dns-query", socks5 = "socks5://127.0.0.1:1080" },
# Authenticated SOCKS5 proxy:
# { url = "https://8.8.4.4/dns-query", socks5 = "socks5://127.0.0.1:1080", username = "user", password = "password" },
]
# Cache configuration
= true
= "/tmp/dnsproxy-cache.toml"
= "50M"
= "1d"
# Concurrency rate limit (0 to disable)
= 0
# IPv6 (AAAA) filtering
= false
= [
"example.org",
"*.example.com",
]
Deployment
Option 1: Systemd Service (Linux)
A production-ready systemd unit file is available at deployment/dnsproxy.service. It is hardened with CAP_NET_BIND_SERVICE to allow binding to privileged port 53 without running as root.
# 1. Build and copy binary
# 2. Create unprivileged system user
# 3. Create directories and config
# 4. Install systemd service
# 5. Check status and logs
Option 2: Docker & Docker Compose
Using Docker:
# Build image
# Run container
Using Docker Compose:
Publishing to Crates.io
To publish this package to crates.io:
-
Verify package files and build:
-
Dry run publish:
-
Publish to crates.io:
Makefile Shortcuts
A Makefile is provided for common development and deployment workflows:
License
Licensed under the Apache License, Version 2.0 (LICENSE-APACHE or LICENSE).