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