ferrousnetworking/ferrous-dns repository overview

⁠Ferrous DNS

High-performance DNS server with network-wide ad-blocking, written in Rust

Documentation⁠ • Quick Start⁠ • Configuration⁠ • Benchmarks⁠ • Roadmap⁠

⁠Documentation

Full documentation is available at ferrous-networking.github.io/ferrous-dns⁠.

⁠Performance

The benchmark runs three scenarios against a 410,000-name working set, and all three are published — including the query log result, which is the one that still costs.

Resolving from cache, blocking off — at 847,711 queries/second (median of 3 runs, 8-core cpuset) ferrous-dns delivers throughput in the same tier as the resolvers written in C and C++, while running a full feature stack (DNS server, REST API, Web UI, SQLite query log, blocking engine) in a single process, which those resolvers do not have. Against the feature-comparable ad-blocking servers the gap is an order of magnitude: 9.9x Blocky, 7.2x AdGuard Home, 43x Pi-hole.

With a 1,000,000-rule blocklist enabled, throughput holds at 834,485 q/s — blocking costs 1.6%, and ferrous-dns runs 7.5x AdGuard Home (111,238) and 8.5x Blocky (97,947) on the identical rule set.

Turning the query log on is what costs. Throughput falls to 262,298 q/s, 69% below blocking alone, and the log is not lossless: this run dropped 144,447 entries. The producer uses a non-blocking send on a bounded channel and discards rows when that channel is full, so the number above is the cost of logging what fit, not of logging everything.

Full benchmark report⁠

⁠Installation

⁠Docker

docker run -d \
  --name ferrous-dns \
  --restart always \
  --network host \
  --user 1000:1000 \
  -e FERROUS_CONFIG=/data/config/ferrous-dns.toml \
  -e FERROUS_DATABASE=/data/db/ferrous.db \
  -e FERROUS_DNS_PORT=53 \
  -e FERROUS_WEB_PORT=8080 \
  -e FERROUS_BIND_ADDRESS=0.0.0.0 \
  -e FERROUS_LOG_LEVEL=info \
  -e TZ=America/Sao_Paulo \
  --dns 10.0.0.1 \
  --cap-add NET_BIND_SERVICE \
  ferrousnetworking/ferrous-dns:latest

Access the dashboard at http://localhost:8080

See full installation guide⁠ for Docker Compose, build from source, and Raspberry Pi setup.

⁠Docker Compose

services:
  ferrous-dns:
    image: ferrousnetworking/ferrous-dns:latest
    container_name: ferrous-dns
    restart: always
    network_mode: host
    user: "1000:1000"
    environment:
      - FERROUS_CONFIG=/data/config/ferrous-dns.toml
      - FERROUS_DATABASE=/data/db/ferrous.db
      - FERROUS_DNS_PORT=53
      - FERROUS_WEB_PORT=8080
      - FERROUS_BIND_ADDRESS=0.0.0.0
      - FERROUS_LOG_LEVEL=info
      - TZ=America/Sao_Paulo
    dns:
      - 10.0.0.1
    cap_add:
      - NET_BIND_SERVICE
    volumes:
      - ferrous-data:/data/

volumes:
  ferrous-data:

docker compose up -d

⁠Build from Source

git clone https://github.com/ferrous-networking/ferrous-dns.git
cd ferrous-dns
cargo build --release
./target/release/ferrous-dns --config ferrous-dns.toml

⁠Configuration

See the full configuration reference⁠ for all options.

⁠Environment Variables

⁠Features

Performance — Cache docs⁠

• L1/L2 hierarchical cache⁠ — thread-local lock-free L1 + sharded DashMap L2 with LFUK eviction and Bloom filter for negative lookups
• In-flight coalescing — deduplicates concurrent queries for the same domain to a single upstream request
• Single binary — DNS server, REST API, Web UI, and SQLite query log in one process; no extra dependencies

Dashboard — Dashboard docs⁠

• Real-time query log with block/allow actions
• Query rate, blocked queries, top domains, top clients
• Upstream latency graphs and health status
• Dark mode, built with HTMX + Alpine.js + TailwindCSS

Encrypted DNS — Encrypted DNS docs⁠

• Upstream: plain UDP, DoH⁠, DoT⁠, DoQ⁠, and HTTP/3⁠
• Server (listener): DoH and DoT⁠ — serve encrypted DNS directly to clients
• IPv6 upstreams and DNS-name resolvers (e.g. dns.google.com resolved at startup)

Upstream Management — Upstream docs⁠

• Named pools⁠ with priority-based routing and automatic failover
• Resolution strategies: Parallel, Balanced, Failover⁠
• Health checks⁠ with configurable thresholds and global fallback upstreams

Blocking & Filtering — Blocking docs⁠

• Blocklists⁠ with regex patterns and wildcard domains (*.ads.com)
• Allowlist⁠
• 1-click blockable service categories⁠ — Advertising, Analytics, Social Media, Telemetry, Adult Content, Gambling
• CNAME cloaking detection⁠ — catches trackers hiding behind first-party CNAMEs
• Safe Search⁠ enforcement for Google, Bing, YouTube, and DuckDuckGo

Client Management — Client docs⁠

• Auto client detection⁠ by IP, MAC address, and hostname
• Client groups⁠ with independent policies (e.g. Kids, Work, IoT, Guest)
• Parental controls⁠ with time-based scheduling per group
• Conditional forwarding⁠ — route specific domains to internal resolvers

Security — Security docs⁠

• HTTPS⁠ for dashboard and REST API (single port, automatic HTTP -> HTTPS redirect)
• Session-based authentication⁠ (login/logout with rate limiting)
• Named API tokens⁠ (SHA-256 hashed, X-Api-Key header)
• First-run setup wizard⁠ for password configuration
• Self-signed certificate generation⁠ from the UI
• DNS rate limiting⁠ — token bucket per subnet with NXDOMAIN budget, TC=1 slip, and dry-run mode
• TCP/DoT connection limiting⁠ — per-IP RAII guards prevent connection exhaustion
• DNSSEC validation⁠ (RFC 4035)
• PROXY Protocol v2⁠ support

Malware Detection — Malware Detection docs⁠

• DNS tunneling detection⁠ — two-phase detection (hot path O(1) + background statistical analysis) catches C2 beaconing, data exfiltration, and DGA malware via entropy, query rate, unique subdomains, TXT proportion, and NXDOMAIN ratio
• DGA detection⁠ — identifies Domain Generation Algorithm malware (Conficker, Mirai, Emotet, CryptoLocker, GOZ) by scoring SLD entropy, consonant ratio, digit ratio, and n-gram bigram frequency; self-contained, no external feeds required
• DNS rebinding protection⁠ — blocks public domains resolving to private IPs (RFC-1918), preventing browser-based attacks on routers, NAS, and IoT devices
• NXDomain hijack detection⁠ — automatically detects and neutralizes ISP NXDOMAIN interception by probing upstreams with .invalid domains (RFC 6761) and converting hijacked responses back to proper NXDOMAIN
• Response IP filtering⁠ — downloads C2 IP threat feeds (abuse.ch, Feodo Tracker) and blocks DNS responses that resolve to known command-and-control server IPs, stopping malware before it connects

Compatibility & Deployment

• Pi-hole v6 API compatibility⁠ — drop-in replacement for existing integrations and third-party apps
• Docker multi-arch images⁠ (amd64, arm64)
• RFC 1035 compliant: A, AAAA, CNAME, MX, TXT, PTR, NS, SRV, and local DNS records⁠
• Auto PTR generation for local A records

⁠Dashboard

Dashboard docs⁠

⁠Contributing

Bug reports, feature requests, and pull requests are welcome.

• Issues: GitHub Issues⁠
• Discussions: GitHub Discussions⁠
• Docs: Contributing Guide⁠

⁠License

Dual-licensed under MIT⁠ and Apache 2.0⁠.