4 PowerDNS offers full master and slave semantics for replicating domain
5 information. Furthermore, PowerDNS can benefit from native database
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
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.
23 To use native replication, configure your backend storage to do the
24 replication and do not configure PowerDNS to do so.
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
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
47 Master support is OFF by default, turn it on by adding
48 :ref:`setting-master` to the configuration.
51 If you have DNSSEC-signed zones and non-PowerDNS slaves,
52 please check your :ref:`metadata-soa-edit`
56 Notifications are only sent for domains with type MASTER in
57 your backend unless :ref:`setting-slave-renotify` is enabled.
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
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,
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
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:
80 - ``pdns_control notify <domain>`` This instructs PowerDNS to notify
81 all IP addresses it considers to be slaves of this domain.
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.
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.
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
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
116 Receiving a NOTIFY immediately clears the back off period for the
117 respective domain to allow immediately freshness checks for this domain.
120 Slave support is OFF by default, turn it on by adding
121 :ref:`setting-slave` to the configuration.
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.
129 PowerDNS also reacts to notifies by immediately checking if the zone has
130 updated and if so, retransfering it.
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 BIND backend implements
136 transaction semantics by renaming files if and only if they have been
137 retrieved completely and parsed correctly.
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.
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.
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.
155 Master/Slave Setup Requirements
156 -------------------------------
158 Generally to enable a Master/Slave setup you have to take care of
159 following properties.
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>`.
165 IXFR: incremental zone transfers
166 --------------------------------
168 If the 'IXFR' zone metadata item is set to 1 for a zone, PowerDNS will
169 attempt to retrieve zone updates via IXFR.
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.
176 In such cases, make sure to delete the zone contents to force a fresh
179 Finally, IXFR updates that "plug" Empty Non Terminals do not yet remove
180 ENT records. A 'pdnsutil rectify-zone' may be required.
182 PowerDNS itself is currently only able to retrieve updates via IXFR. It
183 can not serve IXFR updates.
185 .. _supermaster-operation:
187 Supermaster: automatic provisioning of slaves
188 ---------------------------------------------
190 .. versionchanged:: 4.2.0
191 Supermaster support needs to be explicitly enabled with the
192 :ref:`setting-superslave` setting.
194 PowerDNS can recognize so called 'supermasters'. A supermaster is a host
195 which is master for domains and for which we are to be a slave. When a
196 master (re)loads a domain, it sends out a notification to its slaves.
197 Normally, such a notification is only accepted if PowerDNS already knows
198 that it is a slave for a domain.
200 However, a notification from a supermaster carries more persuasion. When
201 PowerDNS determines that a notification comes from a supermaster and it
202 is bonafide, it can provision the domain automatically, and configure
203 itself as a slave for that zone.
205 Before a supermaster notification succeeds, the following conditions
209 - :ref:`setting-superslave` support must be enabled
210 - The supermaster must carry a SOA record for the notified domain
211 - The supermaster IP must be present in the 'supermaster' table
212 - 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
213 - If your master sends signed NOTIFY it will mark that TSIG key as the TSIG key used for retrieval as well
214 - If you turn off :ref:`setting-allow-unsigned-supermaster`, then your supermaster(s) are required to sign their notifications.
217 If you use another PowerDNS server as master and have
218 DNSSEC enabled on that server please don't forget to rectify the domains
219 after every change. If you don't do this there is no SOA record
220 available and one requirement will fail.
222 So, to benefit from this feature, a backend needs to know about the IP
223 address of the supermaster, and how PowerDNS will be listed in the set
224 of NS records remotely, and the 'account' name of your supermaster.
225 There is no need to fill the account name out but it does help keep
226 track of where a domain comes from.
229 Removal of zones provisioned using the supermaster must be
230 done on the slaves themselves. As there is no way to signal this removal
231 from the master to the slave.
233 .. _modes-of-operation-axfrfilter:
235 Modifying a slave zone using a script
236 -------------------------------------
238 The PowerDNS Authoritative Server can invoke a Lua script on an incoming
239 AXFR zone transfer. The user-defined function ``axfrfilter`` within your
240 script is invoked for each resource record read during the transfer, and
241 the outcome of the function defines what PowerDNS does with the records.
243 What you can accomplish using a Lua script: - Ensure consistent values
244 on SOA - Change incoming SOA serial number to a YYYYMMDDnn format -
245 Ensure consistent NS RRset - Timestamp the zone transfer with a TXT
248 To enable a Lua script for a particular slave zone, determine the
249 ``domain_id`` for the zone from the ``domains`` table, and add a row to
250 the ``domainmetadata`` table for the domain. Supposing the domain we
251 want has an ``id`` of 3, the following SQL statement will enable the Lua
252 script ``my.lua`` for that domain:
256 INSERT INTO domainmetadata (domain_id, kind, content) VALUES (3, "LUA-AXFR-SCRIPT", "/lua/my.lua");
259 The Lua script must both exist and be syntactically
260 correct; if not, the zone transfer is not performed.
262 Your Lua functions have access to the query codes through a pre-defined
263 Lua table called ``pdns``. For example if you want to check for a CNAME
264 record you can either compare ``qtype`` to the numeric constant 5 or the
265 value ``pdns.CNAME`` -- they are equivalent.
267 If your function decides to handle a resource record it must return a
268 result code of 0 together with a Lua table containing one or more
269 replacement records to be stored in the back-end database (if the table
270 is empty, no record is added). If you want your record(s) to be appended
271 after the matching record, return 1 and table of record(s). If, on the
272 other hand, your function decides not to modify a record, it must return
273 -1 and an empty table indicating that PowerDNS should handle the
274 incoming record as normal.
276 Consider the following simple example:
280 function axfrfilter(remoteip, zone, record)
282 -- Replace each HINFO records with this TXT
283 if record:qtype() == pdns.HINFO then
286 qname = record:qname():toString(),
289 content = "Hello Ahu!"
294 -- Grab each _tstamp TXT record and add a time stamp
295 if record:qtype() == pdns.TXT and string.starts(record:qname():toString(), "_tstamp.") then
298 qname = record:qname():toString(),
299 qtype = record:qtype(),
301 content = os.date("Ver %Y%m%d-%H:%M")
306 -- Append A records with this TXT
307 if record:qtype() == pdns.A then
310 qname = record:qname():toString(),
313 content = "Hello Ahu, again!"
322 function string.starts(s, start)
323 return s.sub(s, 1, s.len(start)) == start
326 Upon an incoming AXFR, PowerDNS calls our ``axfrfilter`` function for
327 each record. All HINFO records are replaced by a TXT record with a TTL
328 of 99 seconds and the specified string. TXT Records with names starting
329 with ``_tstamp.`` get their value (rdata) set to the current time stamp.
330 A records are appended with a TXT record. All other records are