]>
Commit | Line | Data |
---|---|---|
0e2063c3 PL |
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:: | |
9cf95124 | 8 | 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. |
a426f021 | 9 | |
0e2063c3 PL |
10 | For the BIND backend, this information is either stored in the |
11 | :ref:`setting-bind-dnssec-db` or the hybrid database, | |
12 | depending on your settings. | |
13 | ||
14 | For the implementation in non-sql backends, please review your backend's | |
15 | documentation. | |
16 | ||
17 | Apart from raw SQL statements, setting domain metadata can be done with | |
18 | ``pdnsutil set-meta`` and retrieving metadata is done with ``pdnsutil get-meta``. | |
19 | ||
8cf9e4df | 20 | The following options can only be read (not written to) via the HTTP API metadata endpoint. |
160e66e7 | 21 | |
20ee5fa8 | 22 | * API-RECTIFY |
ecd936d4 | 23 | * AXFR-MASTER-TSIG |
20ee5fa8 | 24 | * LUA-AXFR-SCRIPT |
ecd936d4 M |
25 | * NSEC3NARROW |
26 | * NSEC3PARAM | |
27 | * PRESIGNED | |
ecd936d4 M |
28 | * TSIG-ALLOW-AXFR |
29 | ||
20ee5fa8 M |
30 | The option SOA-EDIT-API can not be written or read via the HTTP API metadata endpoint. |
31 | ||
0e2063c3 PL |
32 | .. _metadata-allow-axfr-from: |
33 | ||
34 | ALLOW-AXFR-FROM | |
35 | --------------- | |
36 | ||
37 | Per-zone AXFR ACLs can be stored in the domainmetadata table. | |
38 | ||
39 | Each ACL specifies one subnet (v4 or v6), or the magical value 'AUTO-NS' | |
40 | that tries to allow all potential slaves in. | |
41 | ||
42 | Example: | |
43 | ||
633489be | 44 | .. code-block:: shell |
0e2063c3 PL |
45 | |
46 | pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48 | |
47 | ||
48 | Each ACL has its own row in the database: | |
49 | ||
50 | :: | |
51 | ||
633489be | 52 | sql> select id from domains where name='example.com'; |
0e2063c3 | 53 | 7 |
633489be GD |
54 | sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','AUTO-NS'); |
55 | sql> insert into domainmetadata (domain_id, kind, content) values (7,'ALLOW-AXFR-FROM','2001:db8::/48'); | |
0e2063c3 PL |
56 | |
57 | To disallow all IP's, except those explicitly allowed by domainmetadata | |
58 | records, add ``allow-axfr-ips=`` to ``pdns.conf``. | |
59 | ||
986e4858 PL |
60 | .. _metadata-api-rectify: |
61 | ||
62 | API-RECTIFY | |
63 | ----------- | |
690bd03e | 64 | .. versionadded:: 4.1.0 |
986e4858 PL |
65 | |
66 | This metadata item controls whether or not a zone is fully rectified on changes | |
67 | to the contents of a zone made through the :doc:`API <http-api/index>`. | |
68 | ||
69 | When the ``API-RECTIFY`` value is "1", the zone will be rectified on changes. | |
a7ce955b | 70 | Any other value means that it will not be rectified. If this is not set |
b8cd24cc SH |
71 | at all, rectifying of the zone depends on the config variable |
72 | :ref:`setting-default-api-rectify`. | |
986e4858 | 73 | |
0e2063c3 PL |
74 | .. _metadata-axfr-source: |
75 | ||
76 | AXFR-SOURCE | |
77 | ----------- | |
78 | ||
79 | The IP address to use as a source address for sending AXFR and IXFR | |
80 | requests. | |
81 | ||
82 | ALLOW-DNSUPDATE-FROM, TSIG-ALLOW-DNSUPDATE, FORWARD-DNSUPDATE, SOA-EDIT-DNSUPDATE, NOTIFY-DNSUPDATE | |
83 | --------------------------------------------------------------------------------------------------- | |
84 | ||
85 | See the documentation on :ref:`Dynamic DNS update <dnsupdate-metadata>`. | |
86 | ||
87 | .. _metadata-also-notify: | |
88 | ||
89 | ALSO-NOTIFY | |
90 | ----------- | |
91 | ||
92 | When notifying this domain, also notify this nameserver (can occur | |
8fab0658 | 93 | multiple times). The nameserver may contain an optional port |
0e2063c3 PL |
94 | number. e.g.: |
95 | ||
633489be | 96 | .. code-block:: shell |
0e2063c3 PL |
97 | |
98 | pdnsutil set-meta powerdns.org ALSO-NOTIFY 192.0.2.1:5300 | |
99 | pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1 | |
100 | ||
0e2063c3 PL |
101 | |
102 | AXFR-MASTER-TSIG | |
103 | ---------------- | |
104 | ||
105 | Use this named TSIG key to retrieve this zone from its master, see :ref:`tsig-provision-signed-notify-axfr`. | |
106 | ||
107 | GSS-ALLOW-AXFR-PRINCIPAL | |
108 | ------------------------ | |
5e8d94f1 PD |
109 | .. versionchanged:: 4.3.1 |
110 | ||
111 | GSS support was removed | |
112 | ||
113 | .. versionchanged:: 4.7.0 | |
114 | ||
115 | GSS support was added back | |
0e2063c3 PL |
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>`. | |
6830fcce | 152 | Example content: "1 0 0 -". |
0e2063c3 PL |
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 | ||
39c73478 PD |
170 | .. _metadata-publish-cdnskey-publish-cds: |
171 | ||
0e2063c3 PL |
172 | PUBLISH-CDNSKEY, PUBLISH-CDS |
173 | ---------------------------- | |
174 | ||
02d797b8 | 175 | Whether to publish CDNSKEY and/or CDS records as defined in :rfc:`7344`. |
0e2063c3 PL |
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 | ||
39c73478 PD |
189 | Global defaults for these values can be set via :ref:`setting-default-publish-cdnskey` and :ref:`setting-default-publish-cds`. |
190 | ||
7b4e8eed MH |
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 | ||
0e2063c3 PL |
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 | |
cabb2e9a | 208 | fresh RRSIGs. See the :ref:`DNSSEC |
0e2063c3 PL |
209 | documentation <soa-edit-ensure-signature-freshness-on-slaves>` |
210 | for more information. | |
211 | ||
cd46fc6c PL |
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 | ||
0e2063c3 PL |
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-". |