]>
Commit | Line | Data |
---|---|---|
0e2063c3 PL |
1 | DNS Modes of Operation |
2 | ====================== | |
3 | ||
4 | PowerDNS offers full master and slave semantics for replicating domain | |
5 | information. Furthermore, PowerDNS can benefit from native database | |
6 | replication. | |
7 | ||
8 | .. _native-operation: | |
9 | ||
10 | Native replication | |
11 | ------------------ | |
12 | ||
32b78ab9 JS |
13 | Native replication is the default unless another operation is |
14 | specifically configured. Native replication means that | |
98817c27 JS |
15 | PowerDNS will not send out DNS update notifications, nor will it react |
16 | to them. PowerDNS assumes that the backend is taking care of | |
17 | replication unaided. | |
0e2063c3 PL |
18 | |
19 | MySQL replication has proven to be very robust and well suited, even | |
1ce1cbb7 | 20 | over transatlantic connections between badly peering ISPs. |
0e2063c3 PL |
21 | |
22 | To use native replication, configure your backend storage to do the | |
23 | replication and do not configure PowerDNS to do so. | |
24 | ||
a8b6e3fa AF |
25 | Typically, a database slave will be configured as read-only as |
26 | uni-directional database replication is usually sufficient. A PowerDNS | |
27 | server only requires database write access if it is participating as a | |
28 | master or slave in zone transfers, or has a frontend attached for | |
32b78ab9 | 29 | managing records, etc. |
a8b6e3fa | 30 | |
0e2063c3 | 31 | .. _master-operation: |
42f35564 | 32 | .. _primary-operation: |
0e2063c3 | 33 | |
2f19030e PD |
34 | Primary operation |
35 | ----------------- | |
0e2063c3 PL |
36 | |
37 | When operating as a master, PowerDNS sends out notifications of changes | |
38 | to slaves, which react to these notifications by querying PowerDNS to | |
39 | see if the zone changed, and transferring its contents if it has. | |
40 | Notifications are a way to promptly propagate zone changes to slaves, as | |
41 | described in :rfc:`1996`. Since | |
42 | version 4.0.0, the NOTIFY messages have a TSIG record added (transaction | |
32b78ab9 | 43 | signature) if the zone has been configured to use TSIG and the feature has been |
0e2063c3 PL |
44 | enabled. |
45 | ||
46 | .. warning:: | |
47 | Master support is OFF by default, turn it on by adding | |
48 | :ref:`setting-master` to the configuration. | |
49 | ||
50 | .. warning:: | |
51 | If you have DNSSEC-signed zones and non-PowerDNS slaves, | |
52 | please check your :ref:`metadata-soa-edit` | |
53 | settings. | |
54 | ||
55 | .. warning:: | |
56 | Notifications are only sent for domains with type MASTER in | |
29e8eee7 | 57 | your backend unless :ref:`setting-slave-renotify` is enabled. |
0e2063c3 PL |
58 | |
59 | Left open by :rfc:`1996` is who is to be notified - which is harder to | |
60 | figure out than it sounds. All slaves for this domain must receive a | |
61 | notification but the nameserver only knows the names of the slaves - not | |
62 | the IP addresses, which is where the problem lies. The nameserver itself | |
63 | might be authoritative for the name of its secondary, but not have the | |
64 | data available. | |
65 | ||
66 | To resolve this issue, PowerDNS tries multiple tactics to figure out the | |
32b78ab9 JS |
67 | IP addresses of the slaves and notifies everybody. In contrived |
68 | configurations, this may lead to duplicate notifications being sent out, | |
0e2063c3 PL |
69 | which shouldn't hurt. |
70 | ||
32b78ab9 | 71 | Some backends may be able to detect zone changes, others may choose to |
0e2063c3 PL |
72 | let the operator indicate which zones have changed and which haven't. |
73 | Consult the documentation for your backend to see how it processes | |
74 | changes in zones. | |
75 | ||
76 | To help deal with slaves that may have missed notifications, or have | |
77 | failed to respond to them, several override commands are available via | |
78 | the :ref:`pdns_control <running-pdnscontrol>` tool: | |
79 | ||
80 | - ``pdns_control notify <domain>`` This instructs PowerDNS to notify | |
81 | all IP addresses it considers to be slaves of this domain. | |
82 | ||
83 | - ``pdns_control notify-host <domain> <ip-address>`` This is truly an | |
84 | override and sends a notification to an arbitrary IP address. Can be | |
85 | used in :ref:`setting-also-notify` situations or | |
86 | when PowerDNS has trouble figuring out who to notify - which may | |
87 | happen in contrived configurations. | |
88 | ||
89 | .. _slave-operation: | |
42f35564 | 90 | .. _secondary-operation: |
0e2063c3 | 91 | |
2f19030e PD |
92 | Secondary operation |
93 | ------------------- | |
0e2063c3 | 94 | |
32b78ab9 | 95 | On launch, PowerDNS requests from all backends a list of domains that |
0e2063c3 PL |
96 | have not been checked recently for changes. This should happen every |
97 | '**refresh**' seconds, as specified in the SOA record. All domains that | |
edda49f8 | 98 | are unfresh are then checked for changes over at their primary server. If the |
0e2063c3 | 99 | :ref:`types-SOA` serial number there is higher, the domain is |
32b78ab9 | 100 | retrieved and inserted into the database. In any case, after the check, |
0e2063c3 PL |
101 | the domain is declared 'fresh', and will only be checked again after |
102 | '**refresh**' seconds have passed. | |
103 | ||
edda49f8 CH |
104 | If the serial is equal, PowerDNS as a secondary with a presigned zone |
105 | will also compare the SOA RRSIG (signature). If the signatures are | |
106 | different, the zone is also queued for a zone transfer. | |
107 | This is useful when the primary server updates DNSSEC signatures without | |
108 | changing the zone serial. In some configurations, a PowerDNS primary can | |
109 | exhibit this behaviour. | |
110 | To allow for this check, the DO flag is set on the SOA query towards | |
111 | the primary server. In some conditions, some primary servers answer with | |
112 | a truncated SOA response (indicating TCP is required), and the freshness | |
113 | check will fail. As a workaround, the signature check and DO flag can be | |
114 | turned off by disabling | |
d804bbeb | 115 | :ref:`setting-secondary-check-signature-freshness`. |
343566c5 | 116 | |
0e2063c3 PL |
117 | When the freshness of a domain cannot be checked, e.g. because the |
118 | master is offline, PowerDNS will retry the domain after | |
b37d98ac | 119 | :ref:`setting-xfr-cycle-interval` seconds. |
32b78ab9 | 120 | Every time the domain fails its freshness check, PowerDNS will hold |
0e2063c3 | 121 | back on checking the domain for |
b37d98ac | 122 | ``amount of failures * xfr-cycle-interval`` seconds, with a maximum of |
0e2063c3 PL |
123 | :ref:`setting-soa-retry-default` seconds |
124 | between checks. With default settings, this means that PowerDNS will | |
32b78ab9 | 125 | back off for 1, then 2, then 3, etc. minutes, to a maximum of 60 minutes |
7b6e1c68 KD |
126 | between checks. The same hold back algorithm is also applied if the zone |
127 | transfer fails due to problems on the master, i.e. if zone transfer is | |
128 | not allowed. | |
129 | ||
32b78ab9 JS |
130 | Receiving a NOTIFY immediately clears the back-off period for the |
131 | respective domain to allow immediate freshness checks for this domain. | |
0e2063c3 PL |
132 | |
133 | .. warning:: | |
134 | Slave support is OFF by default, turn it on by adding | |
135 | :ref:`setting-slave` to the configuration. | |
136 | ||
137 | .. note:: | |
138 | When running PowerDNS via the provided systemd service file, | |
139 | `ProtectSystem <http://www.freedesktop.org/software/systemd/man/systemd.exec.html#ProtectSystem=>`_ | |
140 | is set to ``full``, this means PowerDNS is unable to write to e.g. | |
32b78ab9 | 141 | ``/etc`` and ``/home``, possibly being unable to write AXFR'd zones. |
0e2063c3 PL |
142 | |
143 | PowerDNS also reacts to notifies by immediately checking if the zone has | |
144 | updated and if so, retransfering it. | |
145 | ||
146 | All backends which implement this feature must make sure that they can | |
147 | handle transactions so as to not leave the zone in a half updated state. | |
148 | MySQL configured with either BerkeleyDB or InnoDB meets this | |
32b78ab9 | 149 | requirement, as does PostgreSQL. The BIND backend implements |
0e2063c3 PL |
150 | transaction semantics by renaming files if and only if they have been |
151 | retrieved completely and parsed correctly. | |
152 | ||
153 | Slave operation can also be programmed using several | |
154 | :ref:`running-pdnscontrol` commands. The ``retrieve`` | |
155 | command is especially useful as it triggers an immediate retrieval of | |
156 | the zone from the configured master. | |
157 | ||
086fdab6 | 158 | Since 4.5.0, zone transfers are added to a queue and processed according to priority |
a60fc30c RG |
159 | and order of addition. Order levels are (from high to low): pdns control, |
160 | api, notify, serial changed during refresh and signatures changed during | |
161 | refresh. High priority zone transfers are always processed first, in a | |
162 | first in first out order. | |
163 | ||
0e2063c3 PL |
164 | PowerDNS supports multiple masters. For the BIND backend, the native |
165 | BIND configuration language suffices to specify multiple masters, for | |
32b78ab9 | 166 | SQL-based backends, list all master servers separated by commas in the |
0e2063c3 PL |
167 | 'master' field of the domains table. |
168 | ||
169 | Since version 4.0.0, PowerDNS requires that masters sign their | |
170 | notifications. During transition and interoperation with other | |
171 | nameservers, you can use options :ref:`setting-allow-unsigned-notify` to permit | |
172 | unsigned notifications. For 4.0.0 this is turned on by default, but it | |
173 | might be turned off permanently in future releases. | |
174 | ||
175 | Master/Slave Setup Requirements | |
176 | ------------------------------- | |
177 | ||
178 | Generally to enable a Master/Slave setup you have to take care of | |
32b78ab9 | 179 | the following properties. |
0e2063c3 PL |
180 | |
181 | * The :ref:`setting-master`/:ref:`setting-slave` state has to be enabled in the respective ``/etc/powerdns/pdns.conf`` config files. | |
182 | * The nameservers have to be set up correctly as NS domain records i.e. defining a NS and A record for each slave. | |
32b78ab9 | 183 | * Master/Slave state has to be configured on a per-domain basis in the ``domains`` table. Namely, the ``type`` column has to be either ``MASTER`` or ``SLAVE`` respectively and the slave needs a comma-separated list of master node IP addresses in the ``master`` column in the ``domains`` table. :doc:`more to this topic <backends/generic-sql>`. |
0e2063c3 PL |
184 | |
185 | IXFR: incremental zone transfers | |
186 | -------------------------------- | |
187 | ||
188 | If the 'IXFR' zone metadata item is set to 1 for a zone, PowerDNS will | |
189 | attempt to retrieve zone updates via IXFR. | |
190 | ||
191 | .. warning:: | |
192 | If a slave zone changes from non-DNSSEC to DNSSEC, an IXFR | |
193 | update will not set the PRESIGNED flag. In addition, a change in NSEC3 | |
194 | mode will also not be picked up. | |
195 | ||
196 | In such cases, make sure to delete the zone contents to force a fresh | |
197 | retrieval. | |
198 | ||
32b78ab9 | 199 | Finally, IXFR updates that "plug" Empty Non-Terminals do not yet remove |
0e2063c3 PL |
200 | ENT records. A 'pdnsutil rectify-zone' may be required. |
201 | ||
202 | PowerDNS itself is currently only able to retrieve updates via IXFR. It | |
a13849bc | 203 | cannot serve IXFR updates. |
0e2063c3 PL |
204 | |
205 | .. _supermaster-operation: | |
42f35564 | 206 | .. _autoprimary-operation: |
0e2063c3 | 207 | |
42f35564 PD |
208 | Autoprimary: automatic provisioning of secondaries |
209 | -------------------------------------------------- | |
0e2063c3 | 210 | |
42f35564 PD |
211 | .. versionchanged:: 4.5.0 |
212 | Before version 4.5.0, this feature was called 'supermaster' | |
213 | ||
32b78ab9 | 214 | PowerDNS can recognize so-called 'autoprimaries'. An autoprimary is a host |
42f35564 PD |
215 | which is primary for domains and for which we are to be a secondary. When a |
216 | primary (re)loads a domain, it sends out a notification to its secondaries. | |
0e2063c3 | 217 | Normally, such a notification is only accepted if PowerDNS already knows |
42f35564 | 218 | that it is a secondary for a domain. |
0e2063c3 | 219 | |
42f35564 | 220 | However, a notification from an autoprimary carries more persuasion. When |
32b78ab9 | 221 | PowerDNS determines that a notification comes from an autoprimary and it |
0e2063c3 | 222 | is bonafide, it can provision the domain automatically, and configure |
42f35564 | 223 | itself as a secondary for that zone. |
0e2063c3 | 224 | |
42f35564 | 225 | Before an autoprimary notification succeeds, the following conditions |
49f9972c PL |
226 | must be met: |
227 | ||
42f35564 PD |
228 | - :ref:`setting-autosecondary` support must be enabled |
229 | - The autoprimary must carry a SOA record for the notified domain | |
230 | - The autoprimary IP must be present in the ``supermasters`` table in the database on the secondary, along with any name that is in the NS set. | |
231 | - The set of NS records for the domain, as retrieved by the secondary from the autoprimary, must include the name that goes with the IP address in the ``supermasters`` table | |
232 | - If your primary sends signed NOTIFY it will mark that TSIG key as the TSIG key used for retrieval as well | |
233 | - If you turn off :ref:`setting-allow-unsigned-autoprimary`, then your autoprimaries are required to sign their notifications. | |
0e2063c3 PL |
234 | |
235 | .. warning:: | |
42f35564 | 236 | If you use another PowerDNS server as primary and have |
0e2063c3 PL |
237 | DNSSEC enabled on that server please don't forget to rectify the domains |
238 | after every change. If you don't do this there is no SOA record | |
239 | available and one requirement will fail. | |
240 | ||
241 | So, to benefit from this feature, a backend needs to know about the IP | |
42f35564 PD |
242 | address of the autoprimary, and how PowerDNS will be listed in the set |
243 | of NS records remotely, and the 'account' name of your autoprimary. | |
0e2063c3 | 244 | There is no need to fill the account name out but it does help keep |
42f35564 PD |
245 | track of where a domain comes from. |
246 | Additionally, if a secondary selects multiple autoprimaries for a zone based on the name of the primary, it also checks that the ``account`` field is the same for all. | |
247 | Adding a autoprimary can be done either directly in the database, | |
d6f5776f | 248 | or by using the 'pdnsutil add-supermaster' command. |
0e2063c3 PL |
249 | |
250 | .. note:: | |
42f35564 PD |
251 | Removal of zones provisioned using the autoprimary must be |
252 | done on the secondaries themselves, as there is no way to signal this removal | |
253 | from the primary to the secondary. | |
0e2063c3 PL |
254 | |
255 | .. _modes-of-operation-axfrfilter: | |
256 | ||
257 | Modifying a slave zone using a script | |
258 | ------------------------------------- | |
259 | ||
260 | The PowerDNS Authoritative Server can invoke a Lua script on an incoming | |
261 | AXFR zone transfer. The user-defined function ``axfrfilter`` within your | |
262 | script is invoked for each resource record read during the transfer, and | |
263 | the outcome of the function defines what PowerDNS does with the records. | |
264 | ||
265 | What you can accomplish using a Lua script: - Ensure consistent values | |
266 | on SOA - Change incoming SOA serial number to a YYYYMMDDnn format - | |
267 | Ensure consistent NS RRset - Timestamp the zone transfer with a TXT | |
268 | record | |
269 | ||
6b0f8acf | 270 | This script can be enabled like this:: |
0e2063c3 | 271 | |
6b0f8acf | 272 | pdnsutil set-meta example.com LUA-AXFR-SCRIPT /path/to/lua/script.lua |
0e2063c3 PL |
273 | |
274 | .. warning:: | |
275 | The Lua script must both exist and be syntactically | |
276 | correct; if not, the zone transfer is not performed. | |
277 | ||
278 | Your Lua functions have access to the query codes through a pre-defined | |
32b78ab9 | 279 | Lua table called ``pdns``. For example, if you want to check for a CNAME |
0e2063c3 PL |
280 | record you can either compare ``qtype`` to the numeric constant 5 or the |
281 | value ``pdns.CNAME`` -- they are equivalent. | |
282 | ||
283 | If your function decides to handle a resource record it must return a | |
284 | result code of 0 together with a Lua table containing one or more | |
285 | replacement records to be stored in the back-end database (if the table | |
286 | is empty, no record is added). If you want your record(s) to be appended | |
287 | after the matching record, return 1 and table of record(s). If, on the | |
288 | other hand, your function decides not to modify a record, it must return | |
289 | -1 and an empty table indicating that PowerDNS should handle the | |
290 | incoming record as normal. | |
291 | ||
292 | Consider the following simple example: | |
293 | ||
633489be | 294 | .. code-block:: lua |
0e2063c3 PL |
295 | |
296 | function axfrfilter(remoteip, zone, record) | |
297 | ||
298 | -- Replace each HINFO records with this TXT | |
299 | if record:qtype() == pdns.HINFO then | |
300 | resp = {} | |
301 | resp[1] = { | |
8b0f2ac7 | 302 | qname = record:qname():toString(), |
0e2063c3 PL |
303 | qtype = pdns.TXT, |
304 | ttl = 99, | |
305 | content = "Hello Ahu!" | |
306 | } | |
307 | return 0, resp | |
308 | end | |
309 | ||
32b78ab9 | 310 | -- Grab each _tstamp TXT record and add a timestamp |
8b0f2ac7 | 311 | if record:qtype() == pdns.TXT and string.starts(record:qname():toString(), "_tstamp.") then |
0e2063c3 PL |
312 | resp = {} |
313 | resp[1] = { | |
314 | qname = record:qname():toString(), | |
315 | qtype = record:qtype(), | |
316 | ttl = record:ttl(), | |
317 | content = os.date("Ver %Y%m%d-%H:%M") | |
318 | } | |
319 | return 0, resp | |
320 | end | |
321 | ||
322 | -- Append A records with this TXT | |
323 | if record:qtype() == pdns.A then | |
324 | resp = {} | |
325 | resp[1] = { | |
8b0f2ac7 | 326 | qname = record:qname():toString(), |
0e2063c3 PL |
327 | qtype = pdns.TXT, |
328 | ttl = 99, | |
329 | content = "Hello Ahu, again!" | |
330 | } | |
331 | return 1, resp | |
332 | end | |
333 | ||
334 | resp = {} | |
335 | return -1, resp | |
336 | end | |
337 | ||
338 | function string.starts(s, start) | |
339 | return s.sub(s, 1, s.len(start)) == start | |
340 | end | |
341 | ||
342 | Upon an incoming AXFR, PowerDNS calls our ``axfrfilter`` function for | |
343 | each record. All HINFO records are replaced by a TXT record with a TTL | |
344 | of 99 seconds and the specified string. TXT Records with names starting | |
32b78ab9 | 345 | with ``_tstamp.`` get their value (rdata) set to the current timestamp. |
0e2063c3 PL |
346 | A records are appended with a TXT record. All other records are |
347 | unhandled. |