Runbound

Drop-in Unbound replacement — REST API, linear scaling, and no restart ever.

Built just for fun — because reconfiguring Unbound by hand every week gets old.

You run Unbound. It works. But every time you need to add a DNS entry, block a domain, or subscribe to a block list, you edit a config file, reload the daemon, and hope nothing breaks.

Runbound does the same job — and lets you manage everything via a REST API, live, without restart.

Your existing unbound.conf works as-is. Zero migration.

What you get

Installation

Recommended — automatic script

sudo bash <(curl -fsSL https://github.com/redlemonbe/Runbound/releases/latest/download/install.sh)

install.sh automatically configures all interdependent security parameters: capabilities, address families, locked memory, API key, directories and permissions. This is the safest installation method.

Manual installation

Manual installation is possible, but Runbound has many interdependent security parameters in the systemd service file. A mistake or omission is silent — the server starts and runs normally even if a security parameter is missing or incorrect.

Before any manual installation, read docs/hardening.md. Then verify the configuration with:

runbound --check-config /etc/runbound/unbound.conf

Startup logs explicitly confirm each active parameter — check them systematically after every manual install or update.

# Download the static binary (no dependencies)
# Replace vX.Y.Z with the latest version tag from the releases page
curl -LO https://github.com/redlemonbe/Runbound/releases/latest/download/runbound-vX.Y.Z-x86_64-linux-musl
chmod +x runbound-vX.Y.Z-x86_64-linux-musl

# Or point it at your existing Unbound config
sudo ./runbound-vX.Y.Z-x86_64-linux-musl /etc/unbound/unbound.conf

# Test it
dig @127.0.0.1 google.com

DNS live on port 53. REST API live on port 8080 (localhost only, requires Bearer token). No config change needed.

The REST API port is configurable with api-port: 9090 in runbound.conf. See the Configuration Reference.

Raspberry Pi or ARM server? Grab runbound-vX.Y.Z-aarch64-linux-musl instead.

Manage DNS without touching a file

API="http://localhost:8080"
TOKEN="your-api-key"

# Add a DNS entry — live, no restart
curl -s -X POST "$API/dns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"nas.home.","type":"A","value":"192.168.1.10","ttl":300}'

# Block a domain — live
curl -s -X POST "$API/blacklist" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ads.example.com"}'

# Subscribe to URLhaus malware feed — auto-refreshed
curl -s -X POST "$API/feeds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"urlhaus","url":"https://urlhaus.abuse.ch/downloads/hostfile/"}'

# Live query stats
curl -s "$API/stats" -H "Authorization: Bearer $TOKEN"

Performance

Linear scaling — the key architectural difference

BIND9 and Unbound use shared caches protected by locks. Beyond 8–16 cores, contention grows and throughput plateaus.

Runbound is built differently:

• SO_REUSEPORT — one UDP socket per physical core, kernel-distributed. Zero userspace lock on the receive path.
• ArcSwap zone trie — readers take a lock-free snapshot. Any number of cores can read simultaneously with no contention.
• CPU affinity — each worker thread is pinned to a physical core, HyperThreading siblings excluded. Enabled automatically at startup: CPU affinity enabled — physical cores (HT excluded) cores=N
• Adaptive cache — cache size is computed from /proc/meminfo at startup and adjusts automatically under memory pressure. cache size auto-sized from MemAvailable cache_size=N

Result: Runbound scales linearly with core count where BIND9 and Unbound plateau.

QPS
│                                        Runbound  /
│                                               /
│                                            /
│                          BIND9 / Unbound /
│                     ................/
│               _____/                 /
│          __/                    /
│___/                      /
└─────────────────────────────────▶ cores
  2    8    16   32   64

Measured throughput

Benchmarks run from a dedicated client machine (never from the DNS server):

Production tip: Set verbosity: 1 in your unbound.conf. verbosity: 2 (info) logs every DNS query — at high QPS this adds measurable CPU overhead (measured: p99 goes from 0.23 ms at verbosity 1 to 3 ms at verbosity 2 under stress). At verbosity: 1 (warn), per-query logging is disabled and Runbound achieves maximum throughput.

Bare-metal benchmark methodology and full raw data: docs/benchmark-2026-05-20.md
Benchmark tool: dnsmark

XDP Kernel-Bypass Fast Path

Starting with v0.4.14, Runbound includes an AF_XDP fast path enabled in all published binaries. Local-zone DNS queries are handled at the NIC driver level, bypassing the Linux kernel network stack entirely.

Measured latency (local zones):

How it works:

• An eBPF XDP program is attached to the NIC at startup
• UDP/port-53 packets for local zones are answered in user space — zero syscalls on the hot path
• All other queries (recursive, forwarded, unknown names) pass through to the normal hickory-server path via XDP_PASS
• One worker thread per NIC RX queue, sharing rate-limiter and ACL with the normal path

Requirements:

• Linux kernel 5.10+ (6.x recommended)
• CAP_NET_RAW, CAP_NET_ADMIN, CAP_BPF (configured automatically by install.sh)
• LimitMEMLOCK=infinity in the systemd service (configured automatically by install.sh)

Verify XDP is active:

journalctl -u runbound | grep XDP
# INFO runbound: XDP kernel-bypass fast path active iface=eth0

Works on VMs (virtio, copy mode) and bare metal Intel NICs (ixgbe/i40e/ice/igc, native zero-copy).

Full details: docs/xdp.md

Downloads

All releases: github.com/redlemonbe/Runbound/releases

Or build from source: cargo build --release
XDP is enabled by default. To disable at runtime (no recompile needed):

• Add xdp: no to unbound.conf, or
• Pass --no-xdp on the command line: runbound --no-xdp /etc/runbound/unbound.conf

To remove the code entirely at build time: cargo build --release --no-default-features

Example configurations

Ready-to-use configs for common scenarios:

Integration example:

Documentation

Contributing

Pull requests welcome. By submitting a pull request you agree to the Contributor License Agreement.

1. cargo clippy --all-targets --features xdp — zero warnings required
2. cargo test — all tests must pass
3. Security fixes: document with a VUL-NN tag

Support the project

If Runbound saves you time or infrastructure costs:

Bitcoin — 3FP8hkkiu4kwCD1PDFgAv2oq1ZTyXwy3yy
Ethereum — 0xB5eEAf89edA4204Aa9305B068b37A93439cBb680

License

Runbound is open source under the GNU AGPL v3.

What this means: if you use Runbound as part of a commercial service, you must publish your modifications under the same license.

Commercial license: organizations that need to use Runbound without AGPL obligations can purchase a commercial license with priority support. See COMMERCIAL_LICENSE.md.

Copyright (C) 2024-2026 RedLemonBe

Development methodology

How this project was built — and why: METHODOLOGY.md

Runbound's security posture is reinforced using AI-assisted tooling at every release:

• Security audit — white-box code review covering SSRF, injection, timing attacks, DoS vectors, and RFC compliance (see docs/security-audit.md)
• Pentest — black-box API and DNS protocol testing (input validation, amplification, information disclosure, authentication bypass)
• Performance analysis — hot-path profiling and allocation review

AI tools are used exclusively as an adversarial review layer. All findings are triaged and patched by the maintainer.

Runbound is not affiliated with the NLnet Labs Unbound project.