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_mode = "Permissive"
block_private_ptr = true
block_non_fqdn = false
mdns_enabled = false              # passive mDNS/Bonjour listener on UDP 5353
# local_domain = "lan"            # optional — no default
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

Wildcard Records¶

Set hostname to * to answer for every subdomain of domain, instead of listing them one by one:

[[dns.local_records]]
hostname = "*"
domain = "home.lan"
ip = "192.168.1.10"
record_type = "A"
ttl = 300

anything.home.lan and deeper.still.home.lan both resolve to 192.168.1.10.

The rules:

• The domain itself is not covered. *.home.lan does not answer for home.lan (RFC 4592). Add an exact record for the apex if you need one.
• An exact record wins. With both *.home.lan → 192.168.1.10 and nas.home.lan → 192.168.1.50, a query for nas.home.lan gets 192.168.1.50.
• The most specific wildcard wins. *.dev.home.lan beats *.home.lan for api.dev.home.lan.
• A type the wildcard does not carry is answered as NODATA — an empty NOERROR, not a query sent upstream. With only an A record defined, an AAAA for anything.home.lan returns no answer instead of leaking the internal name to your upstream resolver.
• Wildcards are matched before the cache and never cached, so adding or deleting one from the dashboard takes effect on the next query.
• No PTR is generated. A wildcard has no single name for an address to reverse to, so Auto PTR Generation skips it.
• * is accepted only as the leftmost label: * or *.dev in hostname, never inside domain. Anything else is rejected with a 400.

A wildcard needs something to anchor it: set domain, or a global dns.local_domain. A bare * with neither is refused rather than stored as a record that would cover every query.

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¶

Ferrous DNS validates DNSSEC signatures (chain of trust from the root KSK, RSA/ECDSA/Ed25519) on upstream responses. The dnssec_mode setting controls how the validation result is applied:

• AD bit (Authenticated Data, RFC 6840): set only when a response validates as Secure and the client did not set the CD bit.
• CD bit (Checking Disabled, RFC 4035): when a client sets CD, enforcement is skipped for that query so the client can perform its own validation — Strict mode will not SERVFAIL it.
• Fail-open: only a proven Bogus result is enforced. Validation errors, timeouts, and Indeterminate/Insecure results are served (with the AD bit clear), prioritising availability.

[dns]
dnssec_mode = "Strict"   # SERVFAIL on Bogus; "Permissive" validates without rejecting; "Off" disables

Trust anchors¶

Validation starts from the root key-signing key. Ferrous DNS embeds the IANA root trust anchors (root-anchors.xml) in the binary — both that are currently valid: KSK-2017 (key tag 20326), which signs the root today, and KSK-2024 (key tag 38696), scheduled to take over signing on 2026-10-11. Shipping both means the rollover needs no action from you.

To pin your own set instead, point dnssec_trust_anchor_file at a file in DNS presentation format:

[dns]
dnssec_trust_anchor_file = "/etc/ferrous-dns/root.key"

The file takes DS and DNSKEY records, one per line, with ; comments — the format written by unbound-anchor -a /etc/ferrous-dns/root.key and shipped by the dns-root-data package as root.key / root.ds:

; the two current IANA root anchors, in DS form
. IN DS 20326 8 2 E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D
. IN DS 38696 8 2 683D2D0ACB8C9B712A1948B27F741219298D0A450D612C483AF444A4C0FB2B16

Behaviour worth knowing:

• The file replaces the embedded anchors rather than adding to them, so you can retire an anchor and not only introduce one. List every anchor you want trusted.
• A configured file that cannot be read or parsed aborts startup. Falling back to the embedded set would leave you believing you had replaced the trust root when you had not.
• The path is read once at startup. It is deliberately not exposed through the REST API or the web UI, and is not part of a configuration backup, since it names a host path.
• Startup logs the count and the source: DNSSEC trust anchors loaded count=2 source=embedded.

WARN Root zone publishes a KSK that no configured trust anchor covers;
     DNSSEC validation will break once the root signs with it —
     update the trust anchors key_tag=38696 algorithm=8

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
doq_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

DNS Cookies (RFC 7873)¶

DNS Cookies (RFC 7873) protect UDP-based DNS against two classes of attack: source-IP spoofing (an attacker forging queries from a victim's address) and amplification (an attacker using open resolvers to flood a target with large DNS responses). By exchanging a cryptographically verified token on every query/response pair, the server can distinguish legitimate clients from forged traffic before spending resources on resolution.

Permissive mode (default)¶

All queries are answered regardless of cookie status. The server always echoes a fresh HMAC-SHA256 server cookie in every response, so RFC-7873-capable clients learn and cache the cookie automatically.

[dns.dns_cookies]
enabled               = true
server_secret         = ""
secret_rotation_secs  = 3600
require_valid_cookie  = false

Strict mode¶

Queries that arrive without a valid server cookie are rejected immediately, before any upstream lookup is performed.

[dns.dns_cookies]
enabled               = true
server_secret         = "a1b2c3d4e5f6..."   # 64 hex chars (32 bytes)
secret_rotation_secs  = 3600
require_valid_cookie  = true

See Security > DNS Cookies for a full explanation of the handshake and threat model.