docs/domainmetadata.rst

   1 Per zone settings: Domain Metadata
   2 ==================================
   3
   4 Each served zone can have "metadata". Such metadata determines how this
   5 zone behaves in certain circumstances.
   6
   7 .. warning::
   8   Domain metadata is only available for DNSSEC capable
   9   backends! Make sure to enable the proper '-dnssec' setting to benefit.
  10
  11 For the BIND backend, this information is either stored in the
  12 :ref:`setting-bind-dnssec-db` or the hybrid database,
  13 depending on your settings.
  14
  15 For the implementation in non-sql backends, please review your backend's
  16 documentation.
  17
  18 Apart from raw SQL statements, setting domain metadata can be done with
  19 ``pdnsutil set-meta`` and retrieving metadata is done with ``pdnsutil get-meta``.
  20
  21 The following options can only be read (not written to) via the HTTP API metadata endpoint.
  22
  23 * API-RECTIFY
  24 * AXFR-MASTER-TSIG
  25 * LUA-AXFR-SCRIPT
  26 * NSEC3NARROW
  27 * NSEC3PARAM
  28 * PRESIGNED
  29 * TSIG-ALLOW-AXFR
  30
  31 The option SOA-EDIT-API can not be written or read via the HTTP API metadata endpoint.
  32
  33 .. _metadata-allow-axfr-from:
  34
  35 ALLOW-AXFR-FROM
  36 ---------------
  37
  38 Per-zone AXFR ACLs can be stored in the domainmetadata table.
  39
  40 Each ACL specifies one subnet (v4 or v6), or the magical value 'AUTO-NS'
  41 that tries to allow all potential slaves in.
  42
  43 Example:
  44
  45 .. code-block:: shell
  46
  47     pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48
  48
  49 Each ACL has its own row in the database:
  50
  51 ::
  52
  53     sql> select id from domains where name='example.com';
  54     7
  55     sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','AUTO-NS');
  56     sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8::/48');
  57
  58 To disallow all IP's, except those explicitly allowed by domainmetadata
  59 records, add ``allow-axfr-ips=`` to ``pdns.conf``.
  60
  61 .. _metadata-api-rectify:
  62
  63 API-RECTIFY
  64 -----------
  65 .. versionadded:: 4.1.0
  66
  67 This metadata item controls whether or not a zone is fully rectified on changes
  68 to the contents of a zone made through the :doc:`API <http-api/index>`.
  69
  70 When the ``API-RECTIFY`` value is "1", the zone will be rectified on changes.
  71 Any other other value means that it will not be rectified. If this is not set
  72 at all, rectifying of the zone depends on the config variable
  73 :ref:`setting-default-api-rectify`.
  74
  75 .. _metadata-axfr-source:
  76
  77 AXFR-SOURCE
  78 -----------
  79
  80 The IP address to use as a source address for sending AXFR and IXFR
  81 requests.
  82
  83 ALLOW-DNSUPDATE-FROM, TSIG-ALLOW-DNSUPDATE, FORWARD-DNSUPDATE, SOA-EDIT-DNSUPDATE, NOTIFY-DNSUPDATE
  84 ---------------------------------------------------------------------------------------------------
  85
  86 See the documentation on :ref:`Dynamic DNS update <dnsupdate-metadata>`.
  87
  88 .. _metadata-also-notify:
  89
  90 ALSO-NOTIFY
  91 -----------
  92
  93 When notifying this domain, also notify this nameserver (can occur
  94 multiple times). The nameserver may have contain an optional port
  95 number. e.g.:
  96
  97 .. code-block:: shell
  98
  99     pdnsutil set-meta powerdns.org ALSO-NOTIFY 192.0.2.1:5300
 100     pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1
 101
 102 Or in SQL:
 103
 104 .. code-block:: SQL
 105
 106     insert into domainmetadata (domain_id, kind, content) values (7,'ALSO-NOTIFY','192.0.2.1:5300');
 107     insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8:53::1');
 108
 109 AXFR-MASTER-TSIG
 110 ----------------
 111
 112 Use this named TSIG key to retrieve this zone from its master, see :ref:`tsig-provision-signed-notify-axfr`.
 113
 114 GSS-ALLOW-AXFR-PRINCIPAL
 115 ------------------------
 116
 117 Allow this GSS principal to perform AXFR retrieval. Most commonly it is
 118 ``host/something@REALM``, ``DNS/something@REALM`` or ``user@REALM``.
 119 (See :ref:`tsig-gss-tsig`).
 120
 121 GSS-ACCEPTOR-PRINCIPAL
 122 ----------------------
 123
 124 Use this principal for accepting GSS context.
 125 (See :ref:`tsig-gss-tsig`).
 126
 127 IXFR
 128 ----
 129
 130 If set to 1, attempt IXFR when retrieving zone updates. Otherwise IXFR
 131 is not attempted.
 132
 133 LUA-AXFR-SCRIPT
 134 ---------------
 135
 136 Script to be used to edit incoming AXFRs, see :ref:`modes-of-operation-axfrfilter`.
 137 This value will override the :ref:`setting-lua-axfr-script` setting. Use
 138 'NONE' to remove a global script.
 139
 140 NSEC3NARROW
 141 -----------
 142
 143 Set to "1" to tell PowerDNS this zone operates in NSEC3 'narrow' mode.
 144 See ``set-nsec3`` for :doc:`pdnsutil <dnssec/pdnsutil>`.
 145
 146 NSEC3PARAM
 147 ----------
 148
 149 NSEC3 parameters of a DNSSEC zone. Will be used to synthesize the
 150 NSEC3PARAM record. If present, NSEC3 is used, if not present, zones
 151 default to NSEC. See ``set-nsec3`` in :doc:`pdnsutil <dnssec/pdnsutil>`.
 152 Example content: "1 0 1 ab".
 153
 154 .. _metadata-presigned:
 155
 156 PRESIGNED
 157 ---------
 158
 159 This zone carries DNSSEC RRSIGs (signatures), and is presigned. PowerDNS
 160 sets this flag automatically upon incoming zone transfers (AXFR) if it
 161 detects DNSSEC records in the zone. However, if you import a presigned
 162 zone using ``zone2sql`` or ``pdnsutil load-zone`` you must explicitly
 163 set the zone to be ``PRESIGNED``. Note that PowerDNS will not be able to
 164 correctly serve the zone if the imported data is bogus or incomplete.
 165 Also see ``set-presigned`` in :doc:`pdnsutil <dnssec/pdnsutil>`.
 166
 167 If a zone is presigned, the content of the metadata must be "1" (without
 168 the quotes). Any other value will not signal presignedness.
 169
 170 .. _metadata-publish-cdnskey-publish-cds:
 171
 172 PUBLISH-CDNSKEY, PUBLISH-CDS
 173 ----------------------------
 174
 175 Whether to publish CDNSKEY and/or CDS recording defined in :rfc:`7344`.
 176
 177 To publish CDNSKEY records of the KSKs for the zone, set
 178 ``PUBLISH-CDNSKEY`` to ``1``.
 179
 180 To publish CDS records for the KSKs in the zone, set ``PUBLISH-CDS`` to
 181 a comma- separated list of `signature algorithm
 182 numbers <http://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml#ds-rr-types-1>`__.
 183
 184 This metadata can also be set using the
 185 :doc:`pdnsutil <dnssec/pdnsutil>` commands ``set-publish-cdnskey``
 186 and ``set-publish-cds``. For an example for an :rfc:`7344` key rollover,
 187 see the :doc:`guides/kskrollcdnskey`.
 188
 189 Global defaults for these values can be set via :ref:`setting-default-publish-cdnskey` and :ref:`setting-default-publish-cds`.
 190
 191 .. _metadata-slave-renotify:
 192
 193 SLAVE-RENOTIFY
 194 --------------
 195 .. versionadded:: 4.3.0
 196
 197 If set to 1, will make PowerDNS renotify the slaves after an AXFR is received from a master.
 198 Any other value means that no renotifies are done. If not set at all, action will depend on
 199 the :ref:`setting-slave-renotify` setting.
 200
 201 .. _metadata-soa-edit:
 202
 203 SOA-EDIT
 204 --------
 205
 206 When serving this zone, modify the SOA serial number in one of several
 207 ways. Mostly useful to get slaves to re-transfer a zone regularly to get
 208 fresh RRSIGs. See the :ref:`DNSSEC
 209 documentation <soa-edit-ensure-signature-freshness-on-slaves>`
 210 for more information.
 211
 212 .. _metadata-soa-edit-api:
 213
 214 SOA-EDIT-API
 215 ------------
 216
 217 On changes to the contents of a zone made through the :doc:`API <http-api/index>`,
 218 the SOA record will be edited according to the SOA-EDIT-API rules. These rules
 219 are the same as the :ref:`SOA-EDIT-DNSUPDATE <dnsupdate-soa-serial-updates>` rules.
 220 If not set during zone creation, a SOA-EDIT-API metadata record is created and set to ``DEFAULT``.
 221 If this record is removed from the backend, the default behaviour is to not do any SOA editing based on this setting.
 222 This is different from setting ``DEFAULT``.
 223
 224
 225 TSIG-ALLOW-AXFR
 226 ---------------
 227
 228 Allow these named TSIG keys to AXFR this zone, see :ref:`tsig-provision-signed-notify-axfr`.
 229
 230 TSIG-ALLOW-DNSUPDATE
 231 --------------------
 232
 233 This setting allows you to set the TSIG key required to do an :doc:`dnsupdate`.
 234 If :ref:`GSS-TSIG <tsig-gss-tsig>` is enabled, you can put kerberos principals here as well.
 235
 236 Extra metadata
 237 --------------
 238
 239 Through the API and on the ``pdnsutil set-meta`` commandline, metadata
 240 unused by PowerDNS can be added. It is mandatory to prefix this extra
 241 metadata with "X-" and the name of the external application; the API
 242 will only allow this metadata if it starts with "X-".