config.toml Reference

Complete reference for every field in config.toml. All fields are optional unless marked required.

[server]

Field	Type	Default	Description
`listen`	string	`"0.0.0.0:53"`	Bind address and port
`worker_threads`	integer	CPU count	OS threads for the async runtime
`max_tcp_connections`	integer	`1000`	Maximum simultaneous TCP DNS sessions
`tcp_read_timeout`	duration	`"5s"`	Timeout for reading a full TCP message
`data_dir`	path	—	Directory for persisting zone data across restarts
`bind_before_drop`	bool	`true`	Bind port 53 before dropping to the service user

Duration format

Durations are strings: "30s", "5m", "1h30m". Units: ms, s, m, h.

[[zone]]

One [[zone]] block per secondary zone. Multiple blocks are supported.

Field	Type	Default	Description
`name`	string	required	Zone name. Trailing dot is optional.
`primary`	string	required	Primary nameserver `host:port`
`tsig_key`	string	—	Key name from `[tsig.*]`. Strongly recommended.
`refresh_interval`	duration	`"60s"`	SOA poll interval when no NOTIFY arrives
`retry_interval`	duration	`"10s"`	Retry interval after a failed transfer
`expire_grace`	duration	`"0s"`	Serve stale data for this long after SOA expiry
`axfr_timeout`	duration	`"30s"`	Maximum time to wait for a full AXFR
`notify_enabled`	bool	`true`	Accept NOTIFY messages for this zone

Zone name normalisation

Zone names are lower-cased and have a trailing dot appended automatically. "EXAMPLE.COM" and "example.com." are equivalent.

[tsig.*]

Each [tsig."<key-name>"] block defines one TSIG key. The key name is a free-form string that must match the tsig_key field in [[zone]].

Field	Type	Default	Description
`algorithm`	string	required	One of `hmac-sha256`, `hmac-sha512`, `hmac-sha384`, `hmac-sha224`, `hmac-sha1`, `hmac-md5`
`secret`	string	required	Base64-encoded shared secret

[tsig."prod-key"]
algorithm = "hmac-sha256"
secret    = "BASE64_HERE"

[tsig."legacy-key"]
algorithm = "hmac-md5"
secret    = "BASE64_HERE"

hmac-sha256 is the recommended algorithm. hmac-md5 and hmac-sha1 are supported for compatibility with older primaries but not recommended for new deployments.

[log]

Field	Type	Default	Description
`level`	string	`"info"`	Log level: `error`, `warn`, `info`, `debug`, `trace`
`format`	string	`"text"`	Output format: `text` or `json`
`timestamps`	bool	`true`	Include ISO-8601 timestamps in log output
`target`	string	`"stderr"`	Log target: `stderr`, `stdout`, or an absolute file path

The debug and trace levels emit high-volume output. Use only for troubleshooting; do not leave enabled in production.

[metrics]

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the Prometheus metrics endpoint
`listen`	string	`"127.0.0.1:9953"`	Bind address for the HTTP metrics server
`path`	string	`"/metrics"`	URL path for the scrape endpoint

See Monitoring for the full list of exposed metric names.

[acl]

Field	Type	Default	Description
`notify_allow`	array of CIDR	`["0.0.0.0/0", "::/0"]`	Source addresses allowed to send NOTIFY messages
`transfer_allow`	array of CIDR	`[]`	Allow outbound-initiated AXFR from these addresses (rarely needed)

[acl]
notify_allow = [
  "10.0.0.0/8",
  "192.168.0.0/16",
  "2001:db8::/32",
]

Environment variable overrides

Any config value can be overridden with an environment variable of the form BORONDNS__<SECTION>__<KEY> (double underscore as separator, all uppercase):

BORONDNS__SERVER__WORKER_THREADS=8 borondns --config /etc/borondns/config.toml
BORONDNS__LOG__LEVEL=debug borondns --config /etc/borondns/config.toml

Environment variables take precedence over file values.

Config validation

Validate a config file without starting the server:

borondns --config /etc/borondns/config.toml --check
# Config OK: 3 zones, 2 TSIG keys

Reload without restart

BoronDNS supports live config reload via SIGHUP or the borondnsctl command:

# Signal directly
kill -HUP $(pidof borondns)

# Or via the management tool
borondnsctl reload

Zone list changes, TSIG key additions, and log-level changes take effect immediately. Changing listen address or worker_threads requires a full restart.

Configuration CLI Reference