{"id":28203999,"url":"https://github.com/jedisct1/etchdns","last_synced_at":"2026-05-01T19:31:39.458Z","repository":{"id":293237352,"uuid":"983388082","full_name":"jedisct1/EtchDNS","owner":"jedisct1","description":"A new DNS proxy designed for simplicity, security and extensibility with WebAssembly plugins.","archived":false,"fork":false,"pushed_at":"2026-04-17T22:54:36.000Z","size":1213,"stargazers_count":77,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-04-18T00:39:17.581Z","etag":null,"topics":["cache","dns","edgedns","extism","proxy","security","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://etchdns.dnscrypt.info","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jedisct1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["jedisct1"],"open_collective":"dnscrypt"}},"created_at":"2025-05-14T10:02:23.000Z","updated_at":"2026-04-17T22:52:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"afd62dd2-e381-4ad8-863d-70b0666ac1fa","html_url":"https://github.com/jedisct1/EtchDNS","commit_stats":null,"previous_names":["jedisct1/etchdns"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jedisct1/EtchDNS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2FEtchDNS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2FEtchDNS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2FEtchDNS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2FEtchDNS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jedisct1","download_url":"https://codeload.github.com/jedisct1/EtchDNS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2FEtchDNS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32510615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","dns","edgedns","extism","proxy","security","wasm","webassembly"],"created_at":"2025-05-17T04:10:23.268Z","updated_at":"2026-05-01T19:31:39.451Z","avatar_url":"https://github.com/jedisct1.png","language":"Rust","funding_links":["https://github.com/sponsors/jedisct1","https://opencollective.com/dnscrypt"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.github.com/jedisct1/etchdns/master/img/logo.png\" alt=\"EtchDNS Logo\" width=\"300\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eEtchDNS\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA caching DNS proxy with advanced security features\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eVisit the website for complete documentation: \u003ca href=\"https://etchdns.dnscrypt.info\"\u003eEtchDNS\u003c/a\u003e\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#key-features\"\u003eKey Features\u003c/a\u003e •\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e •\n  \u003ca href=\"#use-cases\"\u003eUse Cases\u003c/a\u003e •\n  \u003ca href=\"#advanced-features\"\u003eAdvanced Features\u003c/a\u003e •\n  \u003ca href=\"#performance-tuning\"\u003ePerformance Tuning\u003c/a\u003e •\n  \u003ca href=\"#security\"\u003eSecurity\u003c/a\u003e •\n  \u003ca href=\"#development\"\u003eDevelopment\u003c/a\u003e •\n  \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is EtchDNS?\n\nEtchDNS 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.\n\n**Perfect for:**\n- Organizations seeking to improve DNS performance and security\n- Network administrators needing protection against DNS-based attacks\n- Service providers looking to offload DNS traffic from primary servers\n- Privacy-conscious users wanting greater control over their DNS resolution\n- Developers looking for an extensible DNS platform through WebAssembly\n- Secondary authoritative DNS server compatible with any provider (no zone transfer required)\n- Public or local DNS cache in front of a resolver\n- Intermediary between a DNSCrypt server proxy and a resolver\n\n## Key Features\n\n### 🚀 Performance\n- **Efficient Caching**: Uses the SIEVE algorithm for optimal memory usage\n- **Query Aggregation**: Eliminates duplicate in-flight queries to reduce upstream load\n- **Smart Load Balancing**: Multiple strategies (fastest/p2/random) to distribute queries\n- **EDNS-Client-Subnet**: Improves CDN and geolocation-based DNS responses\n- **Protocol Support**: UDP/TCP (standard DNS) and basic DoH (DNS-over-HTTP)\n- **Planned Protocols**: DNSCrypt, PQDNSCrypt, and Anonymized DNSCrypt for improved security and privacy\n\n### 🔒 Security\n- **Domain Filtering**: Whitelist and blacklist support with allowed/NX zones\n- **IP Validation**: Block suspicious IP ranges, validate client ports, and prevent address spoofing\n- **Rate Limiting**: Fine-grained control for each protocol (UDP/TCP/DoH)\n- **Transaction ID Masking**: Protection against cache poisoning attacks\n- **Privilege Dropping**: Run with minimal system access after initialization (user, group, and chroot)\n- **Thorough Request Validation**: Comprehensive DNS packet validation\n\n### 💪 Reliability\n- **Automatic Failover**: Immediate detection of server outages for seamless query routing\n- **Serve Stale**: Continue serving expired cache entries during upstream failures\n- **Health Monitoring**: Regular probing of upstream servers with configurable intervals\n- **Latency Guarantees**: Ensures consistent response times even during upstream slowdowns\n- **Fine-grained Controls**: Separate connection limits for different protocols and in-flight queries\n\n### 📊 Monitoring\n- **Prometheus Metrics**: Comprehensive observability with Prometheus endpoint\n- **Remote Control API**: HTTP interface for status monitoring and cache management\n- **Detailed Logging**: Configurable query logging with customizable details\n- **Log Rotation**: Size and time-based log rotation with compression support\n\n### 🧩 Extensibility (WebAssembly)\n- **Multi-language Plugin Support**: Create custom plugins in any language that compiles to WebAssembly (C/C++, Zig, AssemblyScript, etc.)\n- **Custom Filter Rules**: Implement advanced filtering logic beyond static blocklists\n- **Dynamic Response Modification**: Modify DNS responses based on custom business logic\n- **Stateful Processing**: Maintain state across DNS queries for complex policy enforcement\n\n## Quickstart\n\n1. Download or clone the repository\n2. Edit a copy of the [`etchdns.toml`](etchdns.toml) configuration file\n3. Run EtchDNS:\n\n```sh\netchdns -c /path/to/etchdns.toml\n```\n\n## Use Cases\n\n### Secondary DNS Server\n\nReduce load on your primary DNS servers and ensure continuity of service:\n\n```toml\n# Secondary DNS server mode\nauthoritative_dns = true\n```\n\nEtchDNS 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.\n\n### Local or Public DNS Cache\n\nImprove performance and reliability for local devices or provide a public DNS service:\n\n```toml\n# Cache mode\nauthoritative_dns = false\n```\n\nConfigure 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.\n\n### DNS Firewall\n\nCreate a protective layer for your network:\n\n```toml\n# Domain blocklist configuration\nnx_zones_file = \"nx_zones.txt\"\n\n# IP address validation and filtering\nenable_strict_ip_validation = true\nblock_private_ips = true\nblock_loopback_ips = true\nblocked_ip_ranges = [\"203.0.113.0/24\", \"198.51.100.0/24\"]\nmin_client_port = 1024\n```\n\nBlock 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.\n\nEtchDNS can be used as an intermediary between a DNSCrypt server proxy (such as [encrypted-dns-server](https://github.com/DNSCrypt/encrypted-dns-server)) and your resolver to reduce load and enhance reliability.\n\n### Custom DNS Processing with WebAssembly\n\nImplement advanced DNS processing logic:\n\n```toml\n# WebAssembly hooks\nhooks_wasm_file = \"hooks.wasm\"\nhooks_wasm_wasi = false  # Set to true if your plugin needs WASI support\n```\n\nUse WebAssembly to implement custom filtering rules, monitoring, or modifications to DNS queries and responses.\n\n## Installation\n\n### From Release Binaries\n\nDownload the latest release from the [releases page](https://github.com/jedisct1/etchdns/releases).\n\n### From Source\n\n1. Ensure you have Rust and Cargo installed\n2. Clone this repository\n3. Build the release version:\n\n```sh\ncargo build --release\n```\n\nThe executable will be available at `target/release/etchdns`.\n\n#### Building with WebAssembly Hooks Support\n\nBy 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:\n\n```sh\ncargo build --release --features hooks\n```\nNote 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.\n\n## Configuration\n\nEtchDNS 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`](etchdns.toml) file.\n\nKey configuration sections include:\n\n- **Basic server settings**: Listen addresses, log level, packet size limits\n- **Upstream DNS servers**: Servers to forward queries to\n- **Load balancing**: Strategy and probe interval\n- **Rate limiting**: Parameters for each protocol\n- **Caching**: Cache size and TTL settings\n- **Domain filtering**: Allowed and blocked zones\n- **IP validation**: Client source IP filtering and security options\n- **EDNS-client-subnet**: Enable/disable and prefix length configuration\n- **Security**: Privilege dropping settings\n\n### Domain Filtering\n\n#### Allowed Zones\n\nCreate a text file with domains that should be allowed:\n\n```\n# Company domains\nexample.com\nexample.org\n\n# Third-party services\ngithub.com\ngoogle.com\n```\n\n#### NX Zones (Blocklist)\n\nCreate a text file with domains that should return NXDOMAIN:\n\n```\n# Advertising domains\nads.example.com\nanalytics.example.com\n\n# Known malicious domains\nmalware.example.net\n```\n\n## Advanced Features\n\n### EDNS-Client-Subnet Support\n\nEtchDNS supports EDNS-client-subnet (ECS) as defined in RFC 7871, which can improve CDN and geolocation-based DNS responses:\n\n```toml\n# EDNS-Client-Subnet configuration\nenable_ecs = true\necs_prefix_v4 = 24  # Send first 24 bits of IPv4 address (hide last 8 bits)\necs_prefix_v6 = 56  # Send first 56 bits of IPv6 address (hide last 72 bits)\n```\n\nWhen 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.\n\n### Remote Control API\n\nEtchDNS provides an HTTP API for remote management:\n\n```toml\n# Control API setup\ncontrol_listen_addresses = [\"127.0.0.1:8080\"]\ncontrol_path = \"/control\"\n```\n\nAvailable endpoints:\n- `GET /control/status`: Get comprehensive server status including uptime, connection stats, and health information\n- `GET /control/cache`: Get cache status information including size, hit/miss rates, and entry counts\n- `DELETE /control/cache`: Clear entire cache\n- `DELETE /control/cache/zone/\u003cexample.com\u003e`: Clear all entries for a specific zone\n- `DELETE /control/cache/name/\u003cexample.com\u003e`: Clear a specific entry by name\n\n### WebAssembly Extensions (WIP)\n\n\u003e **Note**: The WebAssembly extension system is currently under active development. While functional, expect API changes and additional features in future releases.\n\nOne 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:\n\n- C/C++\n- Zig\n- AssemblyScript\n- Go/TinyGo\n- And many others, thanks to Extism.\n\n\u003e **Important**: To use WebAssembly extensions, you must compile EtchDNS with the `hooks` feature flag enabled:\n\u003e ```sh\n\u003e cargo build --release --features hooks\n\u003e ```\n\u003e This includes the Extism WebAssembly runtime, which significantly increases the binary size.\n\n#### Benefits of WebAssembly Extensions:\n\n- **Language Flexibility**: Write extensions in your preferred programming language\n- **Sandboxed Execution**: Extensions run in a secure sandbox with minimal overhead\n- **Hot Reloading**: Update extensions without restarting EtchDNS\n- **Stateful Processing**: Maintain state across DNS queries for complex policy enforcement\n- **Extism Integration**: Built on the powerful Extism plugin system with optional WASI support\n\n#### Current Capabilities:\n\nThe current implementation supports the following hook points:\n\n- `hook_client_query_received`: Called when a client query is received, before checking the cache\n  - Return code 0: Continue normal processing\n  - Return code -1: Return minimal response with REFUSED rcode\n\nHooks receive query information in a structured JSON format and can process data from any language that compiles to WebAssembly.\n\n#### Example Implementation:\n\nEtchDNS includes an example WebAssembly plugin in the [`webassembly-plugins`](webassembly-plugins/) directory. This demonstrates how to create a simple plugin that can influence DNS query processing.\n\nTo use WebAssembly extensions, specify the path to your compiled WASM file:\n\n```toml\n# WebAssembly hooks\nhooks_wasm_file = \"hooks.wasm\"\nhooks_wasm_wasi = false  # Set to true if your plugin needs WASI support\n```\n\n#### Building Your Own Extensions:\n\nSee the [WebAssembly Extension Guide](#building-webassembly-hooks) in the Development section for details on building your own WebAssembly extensions.\n\n## Performance Tuning\n\nFor optimal performance, consider these configuration guidelines:\n\n1. **Cache Size**: Increase `cache_size` based on available memory\n2. **Client Limits**: Adjust `max_udp_clients` and `max_tcp_clients` for your environment\n3. **Load Balancing**: Use `fastest` for highest performance, `p2` for a good balance\n4. **Serve Stale**: Enable `serve_stale_grace_time` for improved reliability\n5. **Rate Limiting**: Set appropriate limits that prevent DoS while allowing legitimate traffic\n6. **In-flight Queries**: Adjust `max_inflight_queries` for query aggregation efficiency\n7. **TTL Settings**: Fine-tune various TTL settings to optimize cache performance\n8. **Probe Interval**: Configure `probe_interval` to balance load balancer accuracy with network overhead\n\n## Security\n\nEtchDNS includes several security features to protect both clients and upstream servers:\n\n- **Run with minimal privileges**: Use the privilege dropping feature\n- **Domain filtering**: Restrict which queries are processed\n- **IP validation**: Block connections from suspicious or problematic source addresses\n- **Rate limiting**: Prevent abuse by limiting queries per client\n- **Transaction ID masking**: Protect against cache poisoning attacks\n\n### IP Validation\n\nEtchDNS includes a robust IP validation system that allows you to control which client IP addresses can use your server:\n\n```toml\n# Enable strict IP validation\nenable_strict_ip_validation = true\n\n# Block private IP address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)\nblock_private_ips = true\n\n# Block loopback IP address ranges (127.0.0.0/8, ::1)\nblock_loopback_ips = true\n\n# Minimum port to allow from clients (ports below this will be rejected)\nmin_client_port = 1024\n\n# List of blocked IP ranges\nblocked_ip_ranges = [\"203.0.113.0/24\", \"198.51.100.0/24\"]\n```\n\nThis 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.\n\n## Development\n\n### Running Tests\n\nRun the standard unit tests:\n\n```sh\ncargo test\n```\n\n### Fuzzing Tests\n\nEtchDNS includes comprehensive fuzzing tests for the DNS parsers:\n\n1. Install cargo-fuzz:\n   ```sh\n   cargo install cargo-fuzz\n   ```\n\n2. Run a specific fuzz target:\n   ```sh\n   cargo fuzz run validate_dns_packet\n   ```\n\nFor more details on available targets, see the [fuzz/README.md](fuzz/README.md) file.\n\n### Building WebAssembly Hooks\n\nTo build a WebAssembly extension for EtchDNS:\n\n1. Make sure you've compiled EtchDNS with hooks support:\n   ```sh\n   cargo build --release --features hooks\n   ```\n\n2. Add the WebAssembly target to your Rust toolchain:\n   ```sh\n   rustup target add wasm32-unknown-unknown\n   ```\n\n3. Build the example Rust plugin or your own extension:\n   ```sh\n   cd webassembly-plugins/rust\n   cargo build --target wasm32-unknown-unknown --release\n   ```\n\n4. The compiled WebAssembly module will be available at `target/wasm32-unknown-unknown/release/etchdns_hooks_rust.wasm`\n\n5. Copy the WebAssembly module to your EtchDNS directory and update the configuration:\n   ```sh\n   cp target/wasm32-unknown-unknown/release/etchdns_hooks_rust.wasm /path/to/etchdns/hooks.wasm\n   ```\n\nAlternatively, you can build the Zig example plugin:\n\n1. Navigate to the Zig plugin directory:\n   ```sh\n   cd webassembly-plugins/zig\n   ```\n\n2. Build the Zig plugin:\n   ```sh\n   zig build\n   ```\n\n3. The compiled WebAssembly module will be available in the `zig-out/bin/` directory\n\nFor 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.\n\n#### WASI Support\n\nIf your WebAssembly plugin requires access to system resources (file system, environment variables, etc.), you can enable WASI support in the configuration:\n\n```toml\n# Enable WASI for WebAssembly hooks\nhooks_wasm_wasi = true\n```\n\nThis allows your plugin to use WASI system calls, but increases the security risk. Only enable this if your plugin specifically needs these capabilities.\n\n\u003e **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.\n\n## License\n\nThis project is licensed under the MIT License.\n\n---\n\n## Future Plans\n\n- **Modern Protocol Support**: Future versions may include support for DNSCrypt and Anonymized DNS, potentially porting functionality from the [encrypted-dns-server](https://github.com/DNSCrypt/encrypted-dns-server) project.\n\n\u003e **Note**: Current DoH support is limited to traditional DoH, not Oblivious DoH (ODoH). For a mature, battle-tested DoH server implementation, consider [doh-server](https://github.com/DNSCrypt/doh-server) instead.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fetchdns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjedisct1%2Fetchdns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fetchdns/lists"}