DNS Discovery by Zone Transfer (BIND)

The dns-axfr plugin reads zones from BIND, or any DNS server that allows a standard zone transfer (AXFR, RFC 5936), and records them as onprem.dns_zone and onprem.dns_record nodes (dns_source = bind). These appear on the DNS page and feed the Certificates page.

Where it runs

Your DNS server is inside your network, so run the plugin through an on-premises relay: the relay carries the plugin and runs it next to the server. The relay must be on the same build as the platform; a relay that is out of date is shown as degraded ("update pending") and jobs sent to it fail with that reason until it is updated. On an air-gapped install the platform runs the plugin directly.

Configuration

Key	Required	Description
server	yes	DNS server host, or host:port
port	no	Defaults to 53
zones	yes	Zones to transfer, comma or space separated. A zone transfer cannot list zones, so name them
tsig_name	no	TSIG key name; set together with tsig_secret
tsig_secret	no	TSIG secret, base64
tsig_algorithm	no	hmac-sha256 (default), hmac-sha512, hmac-sha384, hmac-sha224, hmac-sha1, hmac-md5

Server setup

Allow transfers to the relay only, and sign them with a TSIG key:

key "infracast" { algorithm hmac-sha256; secret "<base64 secret>"; };
zone "example.com" { type primary; file "example.com.zone"; allow-transfer { key "infracast"; }; };

Generate the secret with tsig-keygen -a hmac-sha256 infracast. Keep it in your secrets store.

Behaviour

• Never an empty zone. A refused, unauthenticated, truncated or mismatched transfer is reported as "zone … not collected" with the reason (for example REFUSED, TSIG rejected, NOTAUTH, no such zone) and produces no nodes. Zones that did transfer are still recorded. If no zone transferred, the job fails with the reasons.
• A transfer is accepted only when it is framed by the zone's opening and closing SOA records.
• DNSSEC bookkeeping records (RRSIG, NSEC, NSEC3, NSEC3PARAM) are not recorded.
• Read-only: the plugin only asks the server to transfer zones.

Scope of verification

Verified against BIND 9.18 with TSIG, including refused transfers, a wrong key, and a mix of allowed and refused zones. Other servers that implement RFC 5936 are expected to work but are not verified.

Troubleshooting

REFUSED

The server does not allow this client or key to transfer the zone. Check allow-transfer and the relay's source address.

TSIG rejected

The key name, secret or algorithm does not match the server's.

NOTAUTH

The server is not authoritative for that zone, or the key was required and not accepted.