DNS & Upstream Configuration¶

The [dns] section controls upstream resolution, DNSSEC, local records, and upstream pool management.

Basic DNS Options¶

[dns]
upstream_servers = []
query_timeout = 3
default_strategy = "Parallel"
dnssec_enabled = true
block_private_ptr = true
block_non_fqdn = true
local_domain = "lan"
local_dns_server = "10.0.0.1:53"

Upstream URL Formats¶

Ferrous DNS supports all major DNS transport protocols:

You can also use DNS names directly (resolved at startup):

servers = [
    "doq://dns.adguard-dns.com:853",   # hostname resolved at startup
    "https://dns.google/dns-query",
]

Upstream Pools¶

Pools group upstream servers with a resolution strategy. Multiple pools can be defined with different priorities.

[[dns.pools]]
name = "primary"
strategy = "Parallel"
priority = 1
servers = [
    "doq://dns.adguard-dns.com:853",
    "https://cloudflare-dns.com/dns-query",
    "https://dns.google/dns-query",
]

[[dns.pools]]
name = "fallback"
strategy = "Failover"
priority = 2
servers = [
    "udp://8.8.8.8:53",
    "udp://1.1.1.1:53",
]

Strategies¶

Health Checks¶

Ferrous DNS continuously monitors upstream health and routes around failed servers:

[dns.health_check]
interval = 30           # Seconds between health check probes
timeout = 2000          # Milliseconds to wait for a health response
failure_threshold = 3   # Consecutive failures before marking unhealthy
success_threshold = 2   # Consecutive successes to restore a server

A server is temporarily excluded from rotation when failure_threshold consecutive checks fail, and restored after success_threshold consecutive successes.

Local DNS Records¶

Define static A/AAAA records served directly by Ferrous DNS, bypassing upstream resolution:

[[dns.local_records]]
hostname = "router"
domain = "local"
ip = "192.168.1.1"
record_type = "A"
ttl = 300

[[dns.local_records]]
hostname = "nas"
domain = "local"
ip = "192.168.1.50"
record_type = "A"
ttl = 300

# IPv6
[[dns.local_records]]
hostname = "server"
domain = "local"
ip = "fd00::1"
record_type = "AAAA"
ttl = 300

Auto PTR Generation¶

When you define a local A record, Ferrous DNS automatically creates a PTR record. For example, server.local → 192.168.1.100 also creates 100.1.168.192.in-addr.arpa → server.local.

This means reverse DNS lookups work without any extra configuration.

Conditional Forwarding¶

Route specific domains to internal resolvers (e.g. your AD domain controller, split-horizon DNS):

Conditional forwarding is managed via the dashboard UI (Clients > Groups > Forwarding) or the REST API. It allows you to route queries for specific domains to a designated upstream, while all other queries follow the normal pool routing.

Example use case: route corp.internal to 10.0.0.5:53 (Active Directory) while everything else uses DoH upstreams.

DNSSEC¶

When dnssec_enabled = true, Ferrous DNS validates DNSSEC signatures on all upstream responses. Queries that fail DNSSEC validation return SERVFAIL.

Rate Limiting¶

Token-bucket rate limiting per client subnet protects against query floods and DoS attacks.

[dns.rate_limit]
enabled                    = true
queries_per_second         = 1000
burst_size                 = 500
ipv4_prefix_len            = 24
ipv6_prefix_len            = 48
whitelist                  = ["127.0.0.0/8", "::1/128", "10.0.0.0/8"]
nxdomain_per_second        = 50
slip_ratio                 = 2
dry_run                    = false
stale_entry_ttl_secs       = 300
tcp_max_connections_per_ip = 30
dot_max_connections_per_ip = 15

See Security > Rate Limiting for detailed explanations of each feature.

Supported Record Types¶

Ferrous DNS supports all common DNS record types per RFC 1035:

Local DNS Server¶

[dns]
local_dns_server = "192.168.1.1:53"

local_dns_server points to your router or DHCP server. Ferrous DNS uses it for three distinct purposes.

1. PTR Lookups — Reverse DNS for Clients¶

When a client queries Ferrous DNS, the server knows the client's IP address. To display a human-readable hostname in the dashboard, logs, and per-client group matching, Ferrous DNS issues a PTR (reverse DNS) lookup for that IP.

Client IP: 192.168.1.42
         │
         ▼
Ferrous DNS sends: PTR 42.1.168.192.in-addr.arpa → local_dns_server
         │
         ▼
Router responds:   "desktop-work.lan"
         │
         ▼
Dashboard shows:   desktop-work.lan (192.168.1.42)

Without local_dns_server, clients appear in the dashboard only as raw IP addresses. With it, they appear with their full hostname.

2. DHCP Hostname Resolution¶

Many DHCP servers register client hostnames alongside their leases. local_dns_server allows Ferrous DNS to resolve these names, so devices show up with the same names your router assigns them — without requiring any manual configuration on the Ferrous DNS side.

This is especially useful for:

• Parental control rules tied to device names instead of IPs
• Client group assignment based on hostname patterns
• Dashboard readability when many devices are on the network

3. Upstream Server Name Resolution¶

Upstream server URLs may contain hostnames rather than bare IP addresses:

servers = [
    "doq://dns.adguard-dns.com:853",
    "https://cloudflare-dns.com/dns-query",
    "tls://dns.quad9.net:853",
]

At startup, Ferrous DNS must resolve these hostnames to IP addresses before it can establish connections. If local_dns_server is configured, these startup lookups are sent there first — which matters in environments where:

• The machine running Ferrous DNS has no system resolver configured (common in containers)
• You want to avoid a circular dependency (Ferrous DNS cannot query itself to bootstrap its own upstreams)
• Your internal network routes DNS differently than the default system resolver

Startup: resolve "dns.adguard-dns.com"
              │
              ▼ (if local_dns_server is set)
    192.168.1.1:53  →  returns 94.140.14.14
              │
              ▼
    Connection established to doq://94.140.14.14:853

If local_dns_server is not set, hostname resolution at startup falls back to the system resolver (/etc/resolv.conf).

Recommended Setup¶

For a typical home or office network:

[dns]
local_domain     = "lan"          # short hostnames resolve as name.lan
local_dns_server = "192.168.1.1:53"  # your router's IP

DNS Tunneling Detection¶

DNS tunneling detection is configured under [dns.tunneling_detection]. It is enabled by default and requires no additional setup.

For full documentation including real-world attack examples, configuration reference, confidence scoring, and whitelisting, see the Malware Detection page.

[dns.tunneling_detection]
enabled                    = true
action                     = "block"
max_fqdn_length            = 120
max_label_length           = 50
block_null_queries         = true
entropy_threshold          = 3.8
query_rate_per_apex        = 50
unique_subdomain_threshold = 30
txt_proportion_threshold   = 0.05
nxdomain_ratio_threshold   = 0.20
confidence_threshold       = 0.7
stale_entry_ttl_secs       = 300
domain_whitelist           = []
client_whitelist           = []

DGA Detection¶

DGA (Domain Generation Algorithm) detection analyzes second-level domain names for statistical properties associated with algorithmically generated names. It is enabled by default and requires no external feeds.

For full documentation including signal descriptions, malware family examples, and whitelisting, see the Malware Detection page.

[dns.dga_detection]
enabled                       = true
action                        = "block"
hot_path_confidence_threshold = 0.40
sld_entropy_threshold         = 3.5
sld_max_length                = 24
consonant_ratio_threshold     = 0.75
digit_ratio_threshold         = 0.30
ngram_score_threshold         = 0.6
dga_rate_per_client           = 10
confidence_threshold          = 0.65
stale_entry_ttl_secs          = 300
domain_whitelist              = []
client_whitelist              = []

Response IP Filtering¶

Response IP filtering downloads C2 IP threat feeds and blocks DNS responses that resolve to known command-and-control server IPs. It is disabled by default because it requires configuring external feed URLs.

For full documentation including real-world examples, recommended feeds, and edge cases, see the Malware Detection page.

[dns.response_ip_filter]
enabled                = false      # opt-in (requires feed URLs)
action                 = "block"    # "alert" | "block"
ip_list_urls = [
    # "https://feodotracker.abuse.ch/downloads/ipblocklist.txt",
    # "https://sslbl.abuse.ch/blacklist/sslipblacklist.txt",
]
refresh_interval_secs  = 86400      # 24 hours
ip_ttl_secs            = 604800     # 7 days