Quick Start

This guide covers the essentials. Read the full upstream guide on GitHub → For a specific release, select its tag in the repository.

BoronDNS is a secondary authoritative DNS server for Linux. It transfers zones from a primary using AXFR or IXFR and answers queries over UDP and TCP. The primary remains responsible for zone changes and DNSSEC signing.

Before you start

Install a verified release using the installation guide. You need a primary that permits transfers, a zone hosted on that primary, and any transfer credentials. BoronDNS cannot load a BIND zone file directly.

Allow UDP and TCP to your DNS listener, outbound TCP to the primary's transfer port, and NOTIFY from authorized primaries. Keep management HTTP on loopback or a private network.

Prepare your configuration

After installing a native package or installer archive:

borondns --example-config > borondns.toml

Edit the generated file before proceeding:

Set interfaces.dns to the addresses and ports that should serve DNS.
Set the zone name, primary addresses, and NOTIFY sources.
Configure a shared TSIG key for authenticated transfers.
Set server.zone_cache_directory to a durable directory writable by the service user.
Bind health HTTP explicitly to a private address.

The generated example contains documentation addresses; it cannot transfer your zone unchanged. See configuration for the essential settings.

Validate and start

These steps assume the package or archive installer has created the borondns account and service:

borondns --validate-config borondns.toml
sudo install -d -m 0750 -o root -g borondns /etc/borondns-secondary
sudo install -m 0640 -o root -g borondns borondns.toml /etc/borondns-secondary/config.toml
sudo systemctl start borondns
sudo systemctl status borondns

Continue only after validation succeeds. The runtime user must be able to read the configuration and credentials. Validation does not contact the primary or prove transfer authorization.

Verify DNS and readiness

For a local DNS listener on port 53, replace example.test. with your zone:

curl -fsS http://127.0.0.1:8080/livez
curl -fsS http://127.0.0.1:8080/readyz
dig @127.0.0.1 example.test. SOA +short
dig @127.0.0.1 example.test. SOA +tcp +short
journalctl -u borondns --since '10 minutes ago'

Use your configured listener address and add -p 5300 for a high-port setup. Compare the SOA serial with the primary, then change the primary zone and confirm a refresh reaches the secondary.

Readiness means at least one zone is ACTIVE. Check every expected zone using per-zone monitoring.

Installation