]>
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:: | |
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 | ||
8cf9e4df | 21 | The following options can only be read (not written to) via the HTTP API metadata endpoint. |
160e66e7 | 22 | |
20ee5fa8 | 23 | * API-RECTIFY |
ecd936d4 | 24 | * AXFR-MASTER-TSIG |
20ee5fa8 | 25 | * LUA-AXFR-SCRIPT |
ecd936d4 M |
26 | * NSEC3NARROW |
27 | * NSEC3PARAM | |
28 | * PRESIGNED | |
ecd936d4 M |
29 | * TSIG-ALLOW-AXFR |
30 | ||
20ee5fa8 M |
31 | The option SOA-EDIT-API can not be written or read via the HTTP API metadata endpoint. |
32 | ||
0e2063c3 PL |
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 | ||
633489be | 45 | .. code-block:: shell |
0e2063c3 PL |
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 | ||
633489be | 53 | sql> select id from domains where name='example.com'; |
0e2063c3 | 54 | 7 |
633489be GD |
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'); | |
0e2063c3 PL |
57 | |
58 | To disallow all IP's, except those explicitly allowed by domainmetadata | |
59 | records, add ``allow-axfr-ips=`` to ``pdns.conf``. | |
60 | ||
986e4858 PL |
61 | .. _metadata-api-rectify: |
62 | ||
63 | API-RECTIFY | |
64 | ----------- | |
690bd03e | 65 | .. versionadded:: 4.1.0 |
986e4858 PL |
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. | |
b8cd24cc SH |
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`. | |
986e4858 | 74 | |
0e2063c3 PL |
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 | ||
633489be | 97 | .. code-block:: shell |
0e2063c3 PL |
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 | ||
633489be | 104 | .. code-block:: SQL |
0e2063c3 PL |
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 | ||
39c73478 PD |
170 | .. _metadata-publish-cdnskey-publish-cds: |
171 | ||
0e2063c3 PL |
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 | ||
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-". |