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