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