Per zone settings: Domain Metadata

Each served zone can have “metadata”. Such metadata determines how this zone behaves in certain circumstances.

Warning

When multiple backends are in use, domain metadata is only retrieved from and written to the first DNSSEC-capable or metadata-capable backend, no matter where the related zones live.

For the BIND backend, this information is either stored in the bind-dnssec-db or the hybrid database, depending on your settings.

For the implementation in non-sql backends, please review your backend’s documentation.

Apart from raw SQL statements, setting domain metadata can be done with pdnsutil metadata set and retrieving metadata with pdnsutil metadata get (respectively pdnsutil set-meta and pdnsutil get-meta prior to version 5.0).

The following options can only be read (not written to) via the HTTP API metadata endpoint.

  • AXFR-MASTER-TSIG
  • LUA-AXFR-SCRIPT
  • NSEC3NARROW
  • NSEC3PARAM
  • PRESIGNED
  • SOA-EDIT

The following options cannot be written or read via the HTTP API metadata endpoint.

  • API-RECTIFY
  • ENABLE-LUA-RECORDS
  • SOA-EDIT-API

ALLOW-AXFR-FROM

Per-zone AXFR ACLs can be stored in the domainmetadata table.

Each ACL specifies one subnet (v4 or v6), or the magical value ‘AUTO-NS’ that tries to allow all potential secondaries in.

Example:

pdnsutil metadata set powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48

or, prior to version 5.0:

pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48

Each ACL has its own row in the database:

sql> select id from domains where name='example.com';
7
sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','AUTO-NS');
sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8::/48');

To disallow all IP’s, except those explicitly allowed by domainmetadata records, add allow-axfr-ips= to pdns.conf.

ALLOW-DNSUPDATE-FROM, FORWARD-DNSUPDATE, NOTIFY-DNSUPDATE, SOA-EDIT-DNSUPDATE

See the documentation on Dynamic DNS update.

ALSO-NOTIFY

When notifying this domain, also notify this nameserver (can occur multiple times). The nameserver may contain an optional port number. e.g.:

pdnsutil metadata set powerdns.org ALSO-NOTIFY 192.0.2.1:5300
pdnsutil metadata set powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1

or, prior to version 5.0:

pdnsutil set-meta powerdns.org ALSO-NOTIFY 192.0.2.1:5300
pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1

API-RECTIFY

New in version 4.1.0.

This metadata item controls whether or not a zone is fully rectified on changes to the contents of a zone made through the API.

When the API-RECTIFY value is “1”, the zone will be rectified on changes. Any other value means that it will not be rectified. If this is not set at all, rectifying of the zone depends on the config variable default-api-rectify.

AXFR-MASTER-TSIG

Use this named TSIG key to retrieve this zone from its primary, see Provisioning signed notification and AXFR requests.

AXFR-SOURCE

The IP address to use as a source address for sending AXFR and IXFR requests.

ENABLE-LUA-RECORDS

If set to 1, allows LUA records to be used within this zone, even if enable-lua-records is set to no.

GSS-ACCEPTOR-PRINCIPAL

Use this principal for accepting GSS context. (See GSS-TSIG support).

GSS-ALLOW-AXFR-PRINCIPAL

Changed in version 4.3.1: GSS support was removed

Changed in version 4.7.0: GSS support was added back

Allow this GSS principal to perform AXFR retrieval. Most commonly it is host/something@REALM, DNS/something@REALM or user@REALM. (See GSS-TSIG support).

IXFR

If set to 1, attempt IXFR when retrieving zone updates. Otherwise, IXFR is not attempted.

LUA-AXFR-SCRIPT

Script to be used to edit incoming AXFRs, see Modifying a secondary zone using a script. This value will override the lua-axfr-script setting. Use ‘NONE’ to remove a global script.

NSEC3NARROW

Set to “1” to tell PowerDNS this zone operates in NSEC3 ‘narrow’ mode. See zone set-nsec3 in pdnsutil.

NSEC3PARAM

NSEC3 parameters of a DNSSEC zone. Will be used to synthesize the NSEC3PARAM record. If present, NSEC3 is used, if not present, zones default to NSEC. See zone set-nsec3 in pdnsutil. Example content: “1 0 0 -“.

PRESIGNED

This zone carries DNSSEC RRSIGs (signatures), and is presigned. PowerDNS sets this flag automatically upon incoming zone transfers (AXFR) if it detects DNSSEC records in the zone. However, if you import a presigned zone using zone2sql or pdnsutil zone load you must explicitly set the zone to be PRESIGNED. Note that PowerDNS will not be able to correctly serve the zone if the imported data is bogus or incomplete. Also see zone set-presigned in pdnsutil.

If a zone is presigned, the content of the metadata must be “1” (without the quotes). Any other value will not signal presignedness.

PUBLISH-CDNSKEY, PUBLISH-CDS

Whether to publish CDNSKEY and/or CDS records as defined in RFC 7344.

To publish CDNSKEY records of the KSKs for the zone, set PUBLISH-CDNSKEY to 1.

To publish CDS records for the KSKs in the zone, set PUBLISH-CDS to a comma- separated list of signature algorithm numbers.

This metadata can also be set using the pdnsutil commands zone set-publish-cdnskey and zone set-publish-cds. For an example for an RFC 7344 key rollover, see the KSK Rollover using CDS & CDNSKEY Key Rollover.

Global defaults for these values can be set via default-publish-cdnskey and default-publish-cds.

SIGNALING-ZONE

New in version 5.0.0.

If set to 1 (and the zone is signed and uses NSEC3 narrow mode), this setting will make PowerDNS synthesize CDS/CDNSKEY records obtained from other zones served on the same nameserver, in accordance with RFC 9615.

Typically, this metadata does not need to be set manually; instead, you can use pdnsutil set-signaling-zone $zone. This command not only configures this metadata but also takes care of the other preconditions needed to properly set up a signaling zone. For details, see Authenticated Bootstrapping (RFC 9615).

SLAVE-RENOTIFY

New in version 4.3.0.

If set to 1, will make PowerDNS renotify the secondaries after an AXFR is received from a primary. Any other value means that no renotifies are done. If not set at all, action will depend on the secondary-do-renotify setting.

SOA-EDIT

When serving this zone, modify the SOA serial number in one of several ways. Mostly useful to get secondaries to re-transfer a zone regularly to get fresh RRSIGs. See the DNSSEC documentation for more information.

SOA-EDIT-API

On changes to the contents of a zone made through the API, the SOA record will be edited according to the SOA-EDIT-API rules. These rules are the same as the SOA-EDIT-DNSUPDATE rules. If not set during zone creation, a SOA-EDIT-API metadata record is created and set to DEFAULT. If this record is removed from the backend, the default behaviour is to not do any SOA editing based on this setting. This is different from setting DEFAULT.

TSIG-ALLOW-AXFR

Allow these named TSIG keys to AXFR this zone, see Provisioning signed notification and AXFR requests.

TSIG-ALLOW-DNSUPDATE

This setting allows you to set the TSIG key required to do an Dynamic DNS Update (RFC 2136). If GSS-TSIG is enabled, you can put Kerberos principals here as well.

Extra metadata

Through the API and on the pdnsutil metadata set commandline, metadata unused by PowerDNS can be added. It is mandatory to prefix this extra metadata with “X-” and the name of the external application; the API will only allow this metadata if it starts with “X-“.