TSIG Setup

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

TSIG authenticates transfer messages using a shared secret. Configure the same key name, algorithm, and secret on the primary and BoronDNS. Generate the secret once and distribute it securely to both sides.

Create a secret

For an HMAC-SHA256 key:

openssl rand -base64 32

Store the result as a single canonical padded Base64 value in /etc/borondns-secondary/transfer-key.secret. The file must be regular, readable by the runtime user, not world-readable, and not group/world-writable. A root-owned file with group borondns and mode 0640 meets those permissions. Final-component symlinks are rejected.

Reference the key

Adapt your existing zone entry and add the key declaration:

[transfer]
require_tsig = true

[[zones]]
name = "example.test."
primaries = ["192.0.2.53:53"]
notify_sources = ["192.0.2.53"]
tsig_key = "transfer-key."

[[tsig_keys]]
name = "transfer-key."
algorithm = "hmac-sha256"
secret_file = "/etc/borondns-secondary/transfer-key.secret"

Replace the zone and primary with your deployment values. Configure the primary to authorize transfers for this key and send NOTIFY to the secondary's DNS address.

Use exactly one of secret or secret_file. Supported algorithms are SHA-256, SHA-384, SHA-512, and legacy SHA-1; MD5 is rejected. Prefer SHA-256 or stronger.

Validate and troubleshoot

Validate the configuration, restart the service, and compare the served SOA serial with the primary. Keep host clocks synchronized within the configured TSIG fudge window.

For independent transfer checks with dig, use -k with a protected BIND-format key file. Avoid placing secrets in command arguments. The raw Base64 file used by BoronDNS is not a BIND key file.

Encryption and rotation

TSIG authenticates messages; use XoT for outbound transfer encryption. BoronDNS uses TLS 1.3 with no cleartext fallback after TLS failure. See TSIG and XoT configuration for trust anchors and optional mutual TLS.

For managed rotation, follow the secret-store guide. Switching a secret-store generation alone does not request a reload.