Configuration

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

Generate a complete starting configuration with borondns --example-config. The default service path is /etc/borondns-secondary/config.toml.

Listeners and a zone

This small example uses local high ports and an unsigned transfer. Use it only on a trusted private test network. Replace the documentation primary and zone name, and create the cache directory with write access for the runtime user.

[server]
zone_cache_directory = "/var/lib/borondns/zones"
log_level = "info"
log_format = "json"

[interfaces]
dns = ["127.0.0.1:5300"]

[health]
bind_address = "127.0.0.1"
bind_port = 8080

[[zones]]
name = "example.test."
primaries = ["192.0.2.53:53"]
notify_sources = ["192.0.2.53"]

interfaces.dns serves both UDP and TCP and receives NOTIFY. Add more [[zones]] entries for additional zones. For public service, select the intended listener addresses and configure TSIG authentication.

Management and transfer addresses

Set health.bind_address and health.bind_port together. With no health or management listener configured, no management listener opens. Keep this plain HTTP interface private.

If transfers need a dedicated local source address, use interfaces.transfer, for example ["192.0.2.11:0"]. The OS otherwise selects the source. NOTIFY uses the DNS listener.

Validate and apply

borondns --validate-config /etc/borondns-secondary/config.toml
borondns --dump-config /etc/borondns-secondary/config.toml

Validation checks settings and credential material without contacting primaries. The dump redacts inline secrets but still contains paths, addresses, and zone names.

Changes to listeners, policies, static zones, and primaries require a restart; SIGHUP does not reload them. After a successful validation, restart the service and verify the zones.

Advanced configuration

Use the repository for all settings and environment overrides, catalog zone discovery, and large-zone capacity planning. Catalog transfers require TSIG, and static zones take precedence over overlapping catalog members.