Getting Started with Runbound

Runbound ships as a single static binary. No package manager, no runtime dependencies to install separately — download, verify, run.

1. Download and verify

Grab the binary for your platform from the downloads section and verify it before running anything:

curl -LO https://github.com/redlemonbe/Runbound/releases/latest/download/runbound-x86_64-linux-gnu
curl -LO https://github.com/redlemonbe/Runbound/releases/latest/download/runbound-x86_64-linux-gnu.minisig
curl -LO https://github.com/redlemonbe/Runbound/releases/latest/download/SHA256SUMS
curl -LO https://github.com/redlemonbe/Runbound/releases/latest/download/SHA256SUMS.minisig

minisign -Vm SHA256SUMS -P RWSBM9HzDiZpfCD82uTnkeP1Ui30LfWE96C8EtFyI4/WVyLAVxpLzYy/
minisign -Vm runbound-x86_64-linux-gnu -P RWSBM9HzDiZpfCD82uTnkeP1Ui30LfWE96C8EtFyI4/WVyLAVxpLzYy/
sha256sum -c SHA256SUMS --ignore-missing

See the Security page for why every asset carries its own signature, not just a signed checksum file.

2. Install as a systemd service

Runbound is meant to run as a systemd unit, not as an ad hoc nohup process — the shipped unit sets LimitMEMLOCK=infinity and grants CAP_BPF/CAP_NET_RAW, both required for the AF_XDP fast path. Use the bundled installer rather than writing your own unit file:

chmod +x runbound-x86_64-linux-gnu
sudo mv runbound-x86_64-linux-gnu /usr/local/bin/runbound
sudo ./install.sh   # installs the systemd unit, creates /etc/runbound/, generates an API key

If your NIC/driver doesn’t support AF_XDP in DRV mode, Runbound falls back to the generic SKB path automatically. RUNBOUND_DISABLE_XDP=1 is the manual escape hatch if you need to force that fallback (for example, while debugging a driver issue).

3. Minimal configuration

Runbound’s configuration format is intentionally close to unbound.conf — an existing Unbound config is a reasonable starting point. A minimal /etc/runbound/runbound.conf:

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

remote-control:
    control-enable: yes

api:
    listen: 127.0.0.1:8080

webui:
    listen: 0.0.0.0:8090

See the Configuration Reference for the full set of directives, including DNSSEC, forward zones, and master/slave replication.

4. Start it and check it’s answering

sudo systemctl enable --now runbound
sudo systemctl status runbound
dig @127.0.0.1 example.com A

A healthy instance answers immediately with NOERROR (or NXDOMAIN for a name that genuinely doesn’t exist) and, for a DNSSEC-signed zone queried with +dnssec, sets the ad flag and returns the RRSIG records.

5. Talk to the REST API

The install script generates an API key at /etc/runbound/api.key. Every endpoint (zones, blocklists, feeds, stats) requires it as a bearer token:

K=$(cat /etc/runbound/api.key)
curl -H "Authorization: Bearer $K" http://127.0.0.1:8080/api/system

The web dashboard at the webui.listen address uses the same key to log in.