Runbound Configuration Reference

Runbound reads a single configuration file, in a format deliberately close to unbound.conf — the goal is that an existing Unbound configuration is a starting point, not a rewrite.

server

Core listener settings.

server:
    interface: 0.0.0.0
    port: 53
    do-ip4: yes
    do-ip6: yes

• interface — address to listen on for DNS queries. Repeat the directive to listen on multiple addresses.
• port — UDP/TCP port for DNS. 53 for a resolver acting as your network’s default.
• do-ip4 / do-ip6 — enable each address family independently.

forward-zone

Upstream resolvers used when Runbound isn’t authoritative and isn’t doing full recursion itself. Multiple upstreams provide failover; DoT (@853) keeps the query to the upstream encrypted.

forward-zone:
    name: "."
    forward-addr: 9.9.9.9@853
    forward-addr: 1.1.1.1@853

DNSSEC

DNSSEC validation is automatic for any zone that’s actually signed — there is no separate toggle to enable it. Runbound’s validator supports RSA (algorithms 8/10), ECDSA (13/14) and Ed25519 (15); SHA-1-only signatures are rejected fail-closed rather than accepted with a warning. Query with dig +dnssec against a signed name to see the ad flag and RRSIG records; a deliberately broken zone (e.g. dnssec-failed.org) should return SERVFAIL, not a spoofed-looking answer.

remote-control, api, webui

remote-control:
    control-enable: yes

api:
    listen: 127.0.0.1:8080

webui:
    listen: 0.0.0.0:8090

• api.listen — where the REST API binds. Binding to 127.0.0.1 and putting a reverse proxy or SSH tunnel in front is a reasonable default for anything beyond a trusted LAN.
• webui.listen — where the web dashboard binds. The dashboard authenticates with the same API key as the REST API and redirects HTTP to HTTPS.

The API key itself isn’t set in this file — it’s generated by install.sh into /etc/runbound/api.key and rotated by replacing that file’s contents (then restarting the service).

Master/slave replication

A slave node points at a master and receives zone/blocklist/feed updates over an HMAC-signed, encrypted relay:

sync:
    role: slave
    master-addr: 10.0.0.1:8082

The master accepts registrations from slaves automatically — there is no separate step to “add” a slave beyond pointing it at the master’s sync port.

Escape hatches

• RUNBOUND_DISABLE_XDP=1 (environment variable) forces the generic SKB path even on hardware that would otherwise support AF_XDP. Useful when isolating whether a problem is XDP-specific.