etchdns 0.2.1

Caching DNS proxy and forwarding server with load balancing, failover, domain filtering, and WebAssembly plugins
Documentation

What is EtchDNS?

EtchDNS is a caching DNS proxy designed for security and reliability. It acts as a protective layer between clients and upstream DNS servers, providing robust caching, intelligent load balancing, and comprehensive security features.

Perfect for:

  • Organizations seeking to improve DNS performance and security
  • Network administrators needing protection against DNS-based attacks
  • Service providers looking to offload DNS traffic from primary servers
  • Privacy-conscious users wanting greater control over their DNS resolution
  • Developers looking for an extensible DNS platform through WebAssembly
  • Secondary authoritative DNS server compatible with any provider (no zone transfer required)
  • Public or local DNS cache in front of a resolver
  • Intermediary between a DNSCrypt server proxy and a resolver

Key Features

Performance

  • Efficient Caching: Uses the SIEVE algorithm for optimal memory usage
  • Query Aggregation: Eliminates duplicate in-flight queries to reduce upstream load
  • Smart Load Balancing: Multiple strategies (fastest/p2/random) to distribute queries
  • EDNS-Client-Subnet: Improves CDN and geolocation-based DNS responses
  • Protocol Support: UDP/TCP (standard DNS) and basic DoH (DNS-over-HTTP)
  • Planned Protocols: DNSCrypt, PQDNSCrypt, and Anonymized DNSCrypt for improved security and privacy

Security

  • Domain Filtering: Whitelist and blacklist support with allowed/NX zones
  • IP Validation: Block suspicious IP ranges, validate client ports, and prevent address spoofing
  • Rate Limiting: Fine-grained control for each protocol (UDP/TCP/DoH)
  • Transaction ID Masking: Protection against cache poisoning attacks
  • Privilege Dropping: Run with minimal system access after initialization (user, group, and chroot)
  • Thorough Request Validation: Comprehensive DNS packet validation

Reliability

  • Automatic Failover: Immediate detection of server outages for seamless query routing
  • Serve Stale: Continue serving expired cache entries during upstream failures
  • Health Monitoring: Regular probing of upstream servers with configurable intervals
  • Latency Guarantees: Ensures consistent response times even during upstream slowdowns
  • Fine-grained Controls: Separate connection limits for different protocols and in-flight queries

Monitoring

  • Prometheus Metrics: Comprehensive observability with Prometheus endpoint
  • Remote Control API: HTTP interface for status monitoring and cache management
  • Detailed Logging: Configurable query logging with customizable details
  • Log Rotation: Size and time-based log rotation with compression support

Extensibility (WebAssembly)

  • Multi-language Plugin Support: Create custom plugins in any language that compiles to WebAssembly (C/C++, Zig, AssemblyScript, etc.)
  • Custom Filter Rules: Implement advanced filtering logic beyond static blocklists
  • Dynamic Response Modification: Modify DNS responses based on custom business logic
  • Stateful Processing: Maintain state across DNS queries for complex policy enforcement

Quickstart

  1. Download or clone the repository
  2. Edit a copy of the etchdns.toml configuration file
  3. Run EtchDNS:
etchdns -c /path/to/etchdns.toml

Use Cases

Secondary DNS Server

Reduce load on your primary DNS servers and ensure continuity of service:

# Secondary DNS server mode
authoritative_dns = true

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. Compatible with any DNS provider without requiring zone transfers.

Local or Public DNS Cache

Improve performance and reliability for local devices or provide a public DNS service:

# Cache mode
authoritative_dns = false

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.

DNS Firewall

Create a protective layer for your network:

# Domain blocklist configuration
nx_zones_file = "nx_zones.txt"

# IP address validation and filtering
enable_strict_ip_validation = true
block_private_ips = true
block_loopback_ips = true
blocked_ip_ranges = ["203.0.113.0/24", "198.51.100.0/24"]
min_client_port = 1024

Block malicious domains, ads, or unwanted content by configuring the nx_zones.txt file with domains that should return NXDOMAIN responses. Additionally, use IP validation to block connections from suspicious or problematic IP ranges.

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.

Custom DNS Processing with WebAssembly

Implement advanced DNS processing logic:

# WebAssembly hooks
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.

Installation

From Release Binaries

Download the latest release from the releases page.

From Source

  1. Ensure you have Rust and Cargo installed
  2. Clone this repository
  3. Build the release version:
cargo build --release

The executable will be available at target/release/etchdns.

Building with WebAssembly Hooks Support

By default, EtchDNS is built without WebAssembly hooks support to keep the binary size smaller. If you want to enable the hooks functionality, build with the hooks feature flag:

cargo build --release --features hooks

Note that enabling the hooks feature includes a WebAssembly runtime which significantly increases the binary size. Only enable this feature if you plan to use WebAssembly extensions.

Configuration

EtchDNS uses a TOML configuration file to control all aspects of its behavior. A complete example with documentation can be found in the included etchdns.toml file.

Key configuration sections include:

  • Basic server settings: Listen addresses, log level, packet size limits
  • Upstream DNS servers: Servers to forward queries to
  • Load balancing: Strategy and probe interval
  • Rate limiting: Parameters for each protocol
  • Caching: Cache size and TTL settings
  • Domain filtering: Allowed and blocked zones
  • IP validation: Client source IP filtering and security options
  • EDNS-client-subnet: Enable/disable and prefix length configuration
  • Security: Privilege dropping settings

Domain Filtering

Allowed Zones

Create a text file with domains that should be allowed:

# Company domains
example.com
example.org

# Third-party services
github.com
google.com

NX Zones (Blocklist)

Create a text file with domains that should return NXDOMAIN:

# Advertising domains
ads.example.com
analytics.example.com

# Known malicious domains
malware.example.net

Advanced Features

EDNS-Client-Subnet Support

EtchDNS supports EDNS-client-subnet (ECS) as defined in RFC 7871, which can improve CDN and geolocation-based DNS responses:

# EDNS-Client-Subnet configuration
enable_ecs = true
ecs_prefix_v4 = 24  # Send first 24 bits of IPv4 address (hide last 8 bits)
ecs_prefix_v6 = 56  # Send first 56 bits of IPv6 address (hide last 72 bits)

When enabled, EtchDNS will include client IP information in upstream queries, allowing DNS providers to return optimized responses based on the client's location. The prefix lengths control how much of the client's IP address is shared with upstream servers, balancing performance with privacy.

Remote Control API

EtchDNS provides an HTTP API for remote management:

# Control API setup
control_listen_addresses = ["127.0.0.1:8080"]
control_path = "/control"

Available endpoints:

  • GET /control/status: Get comprehensive server status including uptime, connection stats, and health information
  • GET /control/cache: Get cache status information including size, hit/miss rates, and entry counts
  • DELETE /control/cache: Clear entire cache
  • DELETE /control/cache/zone/<example.com>: Clear all entries for a specific zone
  • DELETE /control/cache/name/<example.com>: Clear a specific entry by name

WebAssembly Extensions (WIP)

Note: The WebAssembly extension system is currently under active development. While functional, expect API changes and additional features in future releases.

One of EtchDNS's most powerful features is its ability to be extended through WebAssembly modules. This allows you to implement custom DNS processing logic in any language that compiles to WebAssembly, including:

  • C/C++
  • Zig
  • AssemblyScript
  • Go/TinyGo
  • And many others, thanks to Extism.

Important: To use WebAssembly extensions, you must compile EtchDNS with the hooks feature flag enabled:

cargo build --release --features hooks

This includes the Extism WebAssembly runtime, which significantly increases the binary size.

Benefits of WebAssembly Extensions:

  • Language Flexibility: Write extensions in your preferred programming language
  • Sandboxed Execution: Extensions run in a secure sandbox with minimal overhead
  • Hot Reloading: Update extensions without restarting EtchDNS
  • Stateful Processing: Maintain state across DNS queries for complex policy enforcement
  • Extism Integration: Built on the powerful Extism plugin system with optional WASI support

Current Capabilities:

The current implementation supports the following hook points:

  • hook_client_query_received: Called when a client query is received, before checking the cache
    • Return code 0: Continue normal processing
    • Return code -1: Return minimal response with REFUSED rcode

Hooks receive query information in a structured JSON format and can process data from any language that compiles to WebAssembly.

Example Implementation:

EtchDNS includes an example WebAssembly plugin in the webassembly-plugins directory. This demonstrates how to create a simple plugin that can influence DNS query processing.

To use WebAssembly extensions, specify the path to your compiled WASM file:

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

Building Your Own Extensions:

See the WebAssembly Extension Guide in the Development section for details on building your own WebAssembly extensions.

Performance Tuning

For optimal performance, consider these configuration guidelines:

  1. Cache Size: Increase cache_size based on available memory
  2. Client Limits: Adjust max_udp_clients and max_tcp_clients for your environment
  3. Load Balancing: Use fastest for highest performance, p2 for a good balance
  4. Serve Stale: Enable serve_stale_grace_time for improved reliability
  5. Rate Limiting: Set appropriate limits that prevent DoS while allowing legitimate traffic
  6. In-flight Queries: Adjust max_inflight_queries for query aggregation efficiency
  7. TTL Settings: Fine-tune various TTL settings to optimize cache performance
  8. Probe Interval: Configure probe_interval to balance load balancer accuracy with network overhead

Security

EtchDNS includes several security features to protect both clients and upstream servers:

  • Run with minimal privileges: Use the privilege dropping feature
  • Domain filtering: Restrict which queries are processed
  • IP validation: Block connections from suspicious or problematic source addresses
  • Rate limiting: Prevent abuse by limiting queries per client
  • Transaction ID masking: Protect against cache poisoning attacks

IP Validation

EtchDNS includes a robust IP validation system that allows you to control which client IP addresses can use your server:

# Enable strict IP validation
enable_strict_ip_validation = true

# Block private IP address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
block_private_ips = true

# Block loopback IP address ranges (127.0.0.0/8, ::1)
block_loopback_ips = true

# Minimum port to allow from clients (ports below this will be rejected)
min_client_port = 1024

# List of blocked IP ranges
blocked_ip_ranges = ["203.0.113.0/24", "198.51.100.0/24"]

This helps protect against IP spoofing, abuse from internal networks, and connections from known problematic IP ranges. Client port validation adds another layer of security by blocking connections from privileged ports, which are commonly used in spoofing attacks.

Development

Running Tests

Run the standard unit tests:

cargo test

Fuzzing Tests

EtchDNS includes comprehensive fuzzing tests for the DNS parsers:

  1. Install cargo-fuzz:

    cargo install cargo-fuzz

  2. Run a specific fuzz target:

    cargo fuzz run validate_dns_packet

For more details on available targets, see the fuzz/README.md file.

Building WebAssembly Hooks

To build a WebAssembly extension for EtchDNS:

  1. Make sure you've compiled EtchDNS with hooks support:

    cargo build --release --features hooks

  2. Add the WebAssembly target to your Rust toolchain:

    rustup target add wasm32-unknown-unknown

  3. Build the example Rust plugin or your own extension:

    cd webassembly-plugins/rust
cargo build --target wasm32-unknown-unknown --release

  4. The compiled WebAssembly module will be available at webassembly-plugins/rust/target/wasm32-unknown-unknown/release/hooks_plugin.wasm

  5. Copy the WebAssembly module to your EtchDNS directory and update the configuration:

    cp target/wasm32-unknown-unknown/release/hooks_plugin.wasm /path/to/etchdns/hooks.wasm

Alternatively, you can build the Zig example plugin:

  1. Navigate to the Zig plugin directory:

    cd webassembly-plugins/zig

  2. Build the Zig plugin:

    zig build

  3. The compiled WebAssembly module will be available in the zig-out/bin/ directory

For other languages, consult their respective WebAssembly compilation guides. The key requirement is that the resulting WASM module exports functions that match the hook interface defined by EtchDNS.

WASI Support

If your WebAssembly plugin requires access to system resources (file system, environment variables, etc.), you can enable WASI support in the configuration:

# Enable WASI for WebAssembly hooks
hooks_wasm_wasi = true

This allows your plugin to use WASI system calls, but increases the security risk. Only enable this if your plugin specifically needs these capabilities.

Note: If you try to use WebAssembly hooks with an EtchDNS binary that was compiled without the hooks feature, the hooks functionality will not be available and any hook-related configuration will be ignored.

License

This project is licensed under the MIT License.

Future Plans

  • Modern Protocol Support: Future versions may include support for DNSCrypt and Anonymized DNS, potentially porting functionality from the encrypted-dns-server project.

Note: Current DoH support is limited to traditional DoH, not Oblivious DoH (ODoH). For a mature, battle-tested DoH server implementation, consider doh-server instead.