Use Cases

Reduce load on your primary DNS servers and ensure continuity of service by using EtchDNS as a secondary authoritative DNS server for your zones.

Key Benefits

• Offload traffic from primary DNS servers
• Improve resilience against outages and DDoS attacks
• Compatible with any DNS provider without requiring zone transfers
• Add security features like rate limiting and request validation

Configuration

# In etchdns.toml
authoritative_dns = true

# Upstream servers (your primary DNS servers)
upstream_servers = [
  "primary-dns-1.example.com:53",
  "primary-dns-2.example.com:53"
]

# Cache configuration
cache_size = 10000
serve_stale_grace_time = 86400  # 1 day
serve_stale_ttl = 30

In this mode, EtchDNS acts as a secondary authoritative DNS server for your zones, handling client requests while reducing load on your primary servers and providing protection against common attacks.

Improve performance and reliability for local devices or provide a public DNS service with caching and load distribution across multiple upstream resolvers.

Key Benefits

• Faster DNS resolution through local caching
• Reduced bandwidth usage to upstream DNS servers
• Improved reliability with automatic failover between upstream servers
• Continued service during upstream outages with serve-stale capability

Configuration

# In etchdns.toml
authoritative_dns = false

# Public DNS resolvers
upstream_servers = [
  "8.8.8.8:53",
  "1.1.1.1:53",
  "9.9.9.9:53"
]

# Load balancing
load_balancing_strategy = "fastest"
probe_interval = 60.0

# Cache configuration
cache_size = 50000
serve_stale_grace_time = 86400  # 1 day
serve_stale_ttl = 30

Configure your devices to use EtchDNS as their DNS resolver. It will cache responses, distribute queries across multiple upstream servers, and make your DNS experience more reliable and secure. Can be deployed as either a local network cache or as a public DNS service.

Create a protective layer for your network by blocking malicious domains, ads, or unwanted content using EtchDNS's domain filtering capabilities.

Key Benefits

• Block malicious domains, ads, or unwanted content
• Protect all devices on your network with a single configuration
• Silently drop connections from suspicious IP addresses with IP validation
• Improve network performance by reducing unwanted traffic
• Enhance security by preventing connections to known malicious domains

Configuration

# In etchdns.toml
nx_zones_file = "nx_zones.txt"

# Alternatively, restrict to only allowed domains
allowed_zones_file = "allowed_zones.txt"

# IP validation for additional security
block_private_ips = false   # Set to true in production for better security
block_loopback_ips = false  # Set to true in production for better security
min_client_port = 1024
blocked_ip_ranges = [
  "203.0.113.0/24"  # Example: Block TEST-NET-3 range
]

# Upstream servers (your preferred DNS resolvers)
upstream_servers = [
  "8.8.8.8:53",
  "1.1.1.1:53"
]

Block malicious domains, ads, or unwanted content by configuring the nx_zones.txt file with domains that should return NXDOMAIN responses. For more restrictive environments, you can use the allowed_zones_file to specify which domains are allowed to be resolved.

Implement advanced DNS processing logic using WebAssembly extensions to customize EtchDNS's behavior based on your specific requirements.

Key Benefits

• Create custom filtering rules beyond static blocklists
• Implement dynamic response modification based on business logic
• Develop extensions in any language that compiles to WebAssembly
• Maintain state across DNS queries for complex policy enforcement

Configuration

# In etchdns.toml
hooks_wasm_file = "hooks.wasm"
hooks_wasm_wasi = false  # Set to true if your plugin needs WASI support

Use WebAssembly to implement custom filtering rules, monitoring, or modifications to DNS queries and responses. This allows for sophisticated DNS processing that goes beyond what's possible with static configuration files.

For more information on building WebAssembly extensions, see the WebAssembly Extensions section in the documentation.

EtchDNS can be used as an intermediary between a DNSCrypt server proxy (such as encrypted-dns-server) and your resolver to reduce load and enhance reliability.

Key Benefits

• Reduce load on your DNSCrypt server by caching responses
• Improve reliability with serve-stale capability during resolver outages
• Add additional security features like domain filtering
• Distribute queries across multiple resolvers for better performance

Configuration

# In etchdns.toml
cache_size = 50000
serve_stale_grace_time = 86400  # 1 day
serve_stale_ttl = 30

# Upstream servers (your resolvers)
upstream_servers = [
  "127.0.0.1:5353",  # Local resolver
  "9.9.9.9:53"       # Fallback public resolver
]

# Listen on a different port for the DNSCrypt server
listen_addresses = ["127.0.0.1:5300"]

In this setup, your DNSCrypt server would forward queries to EtchDNS, which would then handle caching and distribution to your resolvers. This reduces the load on both the DNSCrypt server and your resolvers, while improving reliability.