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-axfr-source:
  50
  51 AXFR-SOURCE
  52 -----------
  53
  54 The IP address to use as a source address for sending AXFR and IXFR
  55 requests.
  56
  57 ALLOW-DNSUPDATE-FROM, TSIG-ALLOW-DNSUPDATE, FORWARD-DNSUPDATE, SOA-EDIT-DNSUPDATE, NOTIFY-DNSUPDATE
  58 ---------------------------------------------------------------------------------------------------
  59
  60 See the documentation on :ref:`Dynamic DNS update <dnsupdate-metadata>`.
  61
  62 .. _metadata-also-notify:
  63
  64 ALSO-NOTIFY
  65 -----------
  66
  67 When notifying this domain, also notify this nameserver (can occur
  68 multiple times). The nameserver may have contain an optional port
  69 number. e.g.:
  70
  71 ::
  72
  73     pdnsutil set-meta powerdns.org ALSO-NOTIFY 192.0.2.1:5300
  74     pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1
  75
  76 Or in SQL:
  77
  78 ::
  79
  80     insert into domainmetadata (domain_id, kind, content) values (7,'ALSO-NOTIFY','192.0.2.1:5300');
  81     insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8:53::1');
  82
  83 AXFR-MASTER-TSIG
  84 ----------------
  85
  86 Use this named TSIG key to retrieve this zone from its master, see :ref:`tsig-provision-signed-notify-axfr`.
  87
  88 GSS-ALLOW-AXFR-PRINCIPAL
  89 ------------------------
  90
  91 Allow this GSS principal to perform AXFR retrieval. Most commonly it is
  92 ``host/something@REALM``, ``DNS/something@REALM`` or ``user@REALM``.
  93 (See :ref:`tsig-gss-tsig`).
  94
  95 GSS-ACCEPTOR-PRINCIPAL
  96 ----------------------
  97
  98 Use this principal for accepting GSS context.
  99 (See :ref:`tsig-gss-tsig`).
 100
 101 IXFR
 102 ----
 103
 104 If set to 1, attempt IXFR when retrieving zone updates. Otherwise IXFR
 105 is not attempted.
 106
 107 LUA-AXFR-SCRIPT
 108 ---------------
 109
 110 Script to be used to edit incoming AXFRs, see :ref:`modes-of-operation-axfrfilter`.
 111 This value will override the :ref:`setting-lua-axfr-script` setting. Use
 112 'NONE' to remove a global script.
 113
 114 NSEC3NARROW
 115 -----------
 116
 117 Set to "1" to tell PowerDNS this zone operates in NSEC3 'narrow' mode.
 118 See ``set-nsec3`` for :doc:`pdnsutil <dnssec/pdnsutil>`.
 119
 120 NSEC3PARAM
 121 ----------
 122
 123 NSEC3 parameters of a DNSSEC zone. Will be used to synthesize the
 124 NSEC3PARAM record. If present, NSEC3 is used, if not present, zones
 125 default to NSEC. See ``set-nsec3`` in :doc:`pdnsutil <dnssec/pdnsutil>`.
 126 Example content: "1 0 1 ab".
 127
 128 .. _metadata-presigned:
 129
 130 PRESIGNED
 131 ---------
 132
 133 This zone carries DNSSEC RRSIGs (signatures), and is presigned. PowerDNS
 134 sets this flag automatically upon incoming zone transfers (AXFR) if it
 135 detects DNSSEC records in the zone. However, if you import a presigned
 136 zone using ``zone2sql`` or ``pdnsutil load-zone`` you must explicitly
 137 set the zone to be ``PRESIGNED``. Note that PowerDNS will not be able to
 138 correctly serve the zone if the imported data is bogus or incomplete.
 139 Also see ``set-presigned`` in :doc:`pdnsutil <dnssec/pdnsutil>`.
 140
 141 If a zone is presigned, the content of the metadata must be "1" (without
 142 the quotes). Any other value will not signal presignedness.
 143
 144 PUBLISH-CDNSKEY, PUBLISH-CDS
 145 ----------------------------
 146
 147 Whether to publish CDNSKEY and/or CDS recording defined in :rfc:`7344`.
 148
 149 To publish CDNSKEY records of the KSKs for the zone, set
 150 ``PUBLISH-CDNSKEY`` to ``1``.
 151
 152 To publish CDS records for the KSKs in the zone, set ``PUBLISH-CDS`` to
 153 a comma- separated list of `signature algorithm
 154 numbers <http://www.iana.org/assignments/ds-rr-types/ds-rr-types.xhtml#ds-rr-types-1>`__.
 155
 156 This metadata can also be set using the
 157 :doc:`pdnsutil <dnssec/pdnsutil>` commands ``set-publish-cdnskey``
 158 and ``set-publish-cds``. For an example for an :rfc:`7344` key rollover,
 159 see the :doc:`guides/kskrollcdnskey`.
 160
 161 .. _metadata-soa-edit:
 162
 163 SOA-EDIT
 164 --------
 165
 166 When serving this zone, modify the SOA serial number in one of several
 167 ways. Mostly useful to get slaves to re-transfer a zone regularly to get
 168 fresh RRSIGs. See the :ref:`DNSSEC
 169 documentation <soa-edit-ensure-signature-freshness-on-slaves>`
 170 for more information.
 171
 172 TSIG-ALLOW-AXFR
 173 ---------------
 174
 175 Allow these named TSIG keys to AXFR this zone, see :ref:`tsig-provision-signed-notify-axfr`.
 176
 177 TSIG-ALLOW-DNSUPDATE
 178 --------------------
 179
 180 This setting allows you to set the TSIG key required to do an :doc:`dnsupdate`.
 181 If :ref:`GSS-TSIG <tsig-gss-tsig>` is enabled, you can put kerberos principals here as well.
 182
 183 Extra metadata
 184 --------------
 185
 186 Through the API and on the ``pdnsutil set-meta`` commandline, metadata
 187 unused by PowerDNS can be added. It is mandatory to prefix this extra
 188 metadata with "X-" and the name of the external application; the API
 189 will only allow this metadata if it starts with "X-".