Unbound Knowledge Patch

Unbound Knowledge Patch

Use this skill when configuring, upgrading, operating, building, or debugging Unbound. Start with the quick references below, then open the topic file that matches the task. Treat the deployed binary, unbound-checkconf, service logs, and runtime statistics as authoritative for build-time feature availability.

Reference index

Upgrade-critical defaults and removals

Configure subnetcache explicitly

module-config defaults to "validator iterator" even when Unbound was built with subnet support. If EDNS Client Subnet caching is required, name it:

server:
    module-config: "subnetcache validator iterator"

Review serve-expired defaults

The secure defaults are now:

server:
    serve-expired-ttl: 86400
    serve-expired-client-timeout: 1800

Pin explicit values when an older operational policy must remain unchanged. The reply TTL remains bounded by the record's original TTL.

Account for new local zones

resolver.arpa and service.arpa are served locally by default. Verify forwarding expectations for these names after an upgrade.

Select TLS protocols at runtime

Use tls-protocols to select supported TLS versions. Do not use the removed transient controls tls-use-system-versions or --enable-system-tls. Deployments that require TLS 1.2 must not remain on 1.24.0; 1.24.1 restored it.

Recheck changed limit semantics

• max-global-quota defaults to 200 rather than 128.
• wait-limit: 0 disables all wait limits.
• wait-limit-cookie: 0 can disable limits for COOKIE-validated clients.
• Exceeding a wait limit returns SERVFAIL.
• discard-timeout drops UDP queries, not stream connections.
• Loopback clients are exempt from wait-limit.

Security-first configuration

Bound signature sets

iter-scrub-rrsig caps RRSIG records retained by the iterator scrubber and defaults to 8:

server:
    iter-scrub-rrsig: 8

Protect SVCB and HTTPS answers

private-address filtering applies to SVCB and HTTPS records as well as address records. Keep private ranges complete when using rebinding protection.

Harden glue lookups consistently

harden-unverified-glue also covers missing AAAA lookups started by cache filling. Enable it when that hardened behavior is required on all glue paths.

Apply DNS64 policy in the supported order

To apply RESPIP and RPZ to DNS64-synthesized answers, use:

server:
    module-config: "respip dns64 validator iterator"

Do not assume that inserting cachedb as "respip dns64 validator cachedb iterator" works. DNS64 now also preserves rpz-passthru, respects ECS cache scope, and validates the AAAA leg when DNSSEC is enabled.

Rotate EDNS COOKIE secrets without restart

Persist rollover material with cookie-secret-file, then use add_cookie_secret, activate_cookie_secret, and drop_cookie_secret through unbound-control. Use print_cookie_secrets to inspect the active values.

server:
    cookie-secret-file: "unbound_cookiesecrets.txt"

High-value operational commands

Reload with a short pause

unbound-control fast_reload

fast_reload parses changed configuration in a separate thread and briefly pauses service threads. It handles relevant TLS files, dnstap changes, scrub settings, quota changes, and auth-zone activity. Key-file configuration errors no longer terminate the daemon, but always inspect the returned status and logs.

Inspect selected cache entries

unbound-control cache_lookup example.com
unbound-control cache_lookup +t .

cache_lookup returns cached RRsets and messages for selected domains and includes matching subnet-cache content. +t permits TLD and root names.

Remove one local-data RR

Pass a complete record to avoid deleting every local-data record at the owner:

unbound-control local_data_remove \
  'host.example. 300 IN A 192.0.2.10'

Inspect trust-anchor material

unbound-anchor -l
unbound-anchor -c /etc/unbound/icannbundle.pem

-l prints built-in material; -c selects an external certificate bundle.

Transport quick reference

Enable DNS over QUIC only with build support

Build with libngtcp2 and a QUIC-capable OpenSSL, then configure:

server:
    quic-port: 853
    quic-size: 8m

A build without DoQ support ignores QUIC ports and warns when quic-port is set. Check num.query.quic and mem.quic after enabling it.

Override upstream transport by forward zone

server:
    tcp-upstream: no
    tls-upstream: no

forward-zone:
    name: "."
    forward-tcp-upstream: yes
    forward-tls-upstream: yes

forward-tcp-upstream and forward-tls-upstream override the global choices for that forward zone.

Give control listeners explicit ports

remote-control:
    control-interface: 127.0.0.1@8953

Each control-interface may use IP@port.

Zone and blocking patterns

Block one address family while serving local data

block_aaaa suppresses AAAA lookups like block_a suppresses A lookups. The _wdata variants serve matching local data, recurse transparently for other data, and deny the selected address family:

server:
    local-zone: "v4-only.example." block_aaaa_wdata
    local-data: "v4-only.example. 300 IN A 192.0.2.10"

Avoid circular zone dependencies

Prefer IP addresses for stub- and forward-zone name servers. Hostnames can create a circular resolution dependency; Unbound detects this and logs a warning, but the configuration still needs correction.

Bound zone transfers when needed

max-transfer-size and max-transfer-time limit auth-zone and RPZ transfers. Both are disabled by default, so configure them explicitly for bounded resource use.