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