« back to all changes in this revision
Viewing changes to pdns/docs/pdns.sgml
- browse files at revision 13
- compare with another revision
- download diff
- download tarball
- view history from revision 13
- Committer: Bazaar Package Importer
- Author(s): Matthijs Mohlmann, Matthijs Mohlmann, Christoph Haas
- Date: 2007-04-15 23:23:39 UTC
- mfrom: (1.1.4 upstream)
- Revision ID: james.westby@ubuntu.com-20070415232339-5x3scc8gx04e50um
Tags: 2.9.21-1
[ Matthijs Mohlmann ]
* New upstream release. (Closes: #420294)
* Remove meta pdns package.
* Added new sqlite3 backend package.
* Months and minutes where mixed up. (Closes: #406462)
* Case sensitivity in bind backend caused PowerDNS to not serve a certain
zone. (Closes: #406461)
* Bind backend forgot about zones on a notify. (Closes: #398213)
[ Christoph Haas ]
* Documented incorporated backend bind. (Closes: #415471)
* New upstream release. (Closes: #420294)
* Remove meta pdns package.
* Added new sqlite3 backend package.
* Months and minutes where mixed up. (Closes: #406462)
* Case sensitivity in bind backend caused PowerDNS to not serve a certain
zone. (Closes: #406461)
* Bind backend forgot about zones on a notify. (Closes: #398213)
[ Christoph Haas ]
* Documented incorporated backend bind. (Closes: #415471)
- files added:
- debian/compat
- modules/gsqlite3backend
- pdns/ext
- pdns/ext/nedmalloc
- files removed:
- debian/patches/fix-ipv6-handling.dpatch
- files modified:
- Makefile.in
added
removed
pdns/docs/pdns.sgml
11
11
</affiliation>
12
12
</author>
13
13
14
<PubDate>v2.9.19 $Date: 2006-03-15 19:27:07 +0100 (Wed, 15 Mar 2006) $</PubDate>
14
<PubDate>v2.9.19 $Date: 2007-04-21 11:55:54 +0200 (Sat, 21 Apr 2007) $</PubDate>
15
15
16
16
<Abstract>
17
17
<para>
75
75
for updates. The PDF version is available on <ulink url="http://doc.powerdns.com/pdf">http://doc.powerdns.com/pdf</ulink>, a text file is
76
76
on <ulink url="http://doc.powerdns.com/txt">http://doc.powerdns.com/txt/</ulink>.
77
77
</para>
78
</sect1>
78
79
<sect1 id="changelog">
79
80
<title>Release notes</title>
80
81
<para>
81
82
Before proceeding, it is advised to check the release notes for your PDNS version, as specified in the name of the distribution
82
83
file.
83
84
</para>
85
<sect2 id="changelog-2-9-21"><title>PowerDNS Authoritative Server version 2.9.21</title>
86
<para>
87
Released the 21st of April 2007.
88
</para>
89
<para>
90
This is the first release the PowerDNS Authoritative Server since the Recursor was split off to a separate product, and also marks the transfer
91
of the new technology developed specifically for the recursor, back to the authoritative server.
92
</para>
93
<para>
94
This move has reduced the amount of code of the Authoritative server by over 2000 lines, while improving the quality
95
of the program enormously.
96
</para>
97
<para>
98
However, since so much has been changed, care should be taken when deploying 2.9.21.
99
</para>
100
<para>
101
To signify the magnitude of the underlying improvements, the next release of the PowerDNS Authoritative Server will be called 3.0.
102
</para>
103
<para>
104
This release would not have been possible without large amounts of help and support from the PowerDNS Community. We specifically want to thank
105
Massimo Bandinelli of Italy's <ulink url="http://register.it">Register.it</ulink>, <ulink url="http://aaldering-ict.nl">Dave Aaldering of Aaldering ICT</ulink>,
106
<ulink url="http://true.nl">True BV</ulink>, <ulink url="http://www.xs4all.nl">XS4ALL</ulink>, Daniel Bilik of <ulink url="http://www.neosystem.cz">Neosystem</ulink>,
107
<ulink url="http://www.easydns.com">EasyDNS</ulink>, <ulink url="http://www.siemens.com">Heinrich Ruthensteiner</ulink> of Siemens,
108
<ulink url="http://schwer.us">Augie Schwer</ulink>, <ulink url="http://www.wikipedia.org">Mark Bergsma</ulink>, <ulink url="http://www.forfun.net">Marco Davids</ulink>,
109
<ulink url="http://www.opensuse.org">Marcus Rueckert of OpenSUSE</ulink>, Andre Muraro of <ulink url="http://www.locaweb.com.br">Locaweb</ulink>,
110
Antony Lesuisse, <ulink url="http://www.linuxnetworks.de">Norbert Sendetzky</ulink>, <ulink url="http://www.aruba.it">Marco Chiavacci</ulink>, Christoph Haas,
111
Ralf van der Enden and Ruben Kerkhof.
112
</para>
113
<para>
114
Security issues:
115
<itemizedlist>
116
<listitem>
117
<para>
118
The previous packet parsing and generating code contained no known bugs, but was however very lengthy and overly complex, and might have had
119
security problems. The new code is 'inherently safe' because it relies on bounds-checking C++ constructs. Therefore, a move to 2.9.21 is highly
120
recommended.
121
</para>
122
</listitem>
123
<listitem>
124
<para>
125
Pre-2.9.21, communication between master and server nameservers was not checked as rigidly as possible, possibly allowing third parties to disrupt
126
but not modify such communications.
127
</para>
128
</listitem>
129
</itemizedlist>
130
</para>
131
<para>
132
<warning>
133
<para>
134
The 'bind1' legacy version of our BIND backend has been dropped! There should be no need to rely on this old version anymore, as the main BIND backend
135
has been very well tested recently.
136
</para>
137
</warning>
138
<para>
139
Bugs:
140
<itemizedlist>
141
<listitem>
142
<para>
143
Multi-part TXT records weren't supported. This has been fixed, and regression tests have been added. Code in commits C1016, C996, C994.
144
</para>
145
</listitem>
146
<listitem>
147
<para>
148
Email addresses with embedded dots in SOA records were not parsed correctly, nor were other embedded dots. Noted by 'Bastiaan', fixed in c1026.
149
</para>
150
</listitem>
151
<listitem>
152
<para>
153
BIND backend treated the 'm' TTL modifier as 'months' and not 'minutes'. Closes Debian bug 406462. Addressed in c1026.
154
</para>
155
</listitem>
156
<listitem>
157
<para>
158
Our snapshots were built against a static version of PosgreSQL that was incompatible with many Linux distributions, leading to instant
159
crashes on startup. Fixed in C1022 and C1023.
160
</para>
161
</listitem>
162
<listitem>
163
<para>
164
CNAME referrals to child zones gave improper responses. Noted by Augie Schwer in t123, fixed in c992.
165
</para>
166
</listitem>
167
<listitem>
168
<para>
169
When passing a port number with the <command>recursor</command> setting, this would sometimes generate errors during additional processing. Switched off
170
overly helpful additional processing for recursive queries to remove this problem. Implemented in c1031, spotted by Ralf van der Enden.
171
</para>
172
</listitem>
173
<listitem>
174
<para>
175
NS to a nameserver with the name of the zone itself generated problems. Spotted by Augie Schwer, fixed in c947.
176
</para>
177
</listitem>
178
<listitem>
179
<para>
180
Multi-line records in the BIND backend were not always parsed correctly. Fixed in c1014.
181
</para>
182
</listitem>
183
<listitem>
184
<para>
185
The LOC-record had problems operating outside of the eastern hemisphere of the northern part of the world! Fixed in c1011.
186
</para>
187
</listitem>
188
<listitem>
189
<para>
190
Backends were compiled without multithreading preprocessor flags. As far as we can determine, this would only cause problems for the BIND backend,
191
but we cannot rule out this caused instability in other backends. Fixed in c1001.
192
</para>
193
</listitem>
194
<listitem>
195
<para>
196
The BIND backend was highly unstable under reloads, and leaked memory and file descriptors.
197
Thanks to Mark Bergsma and Massimo Bandinelli for respectively pointing this out to us and testing
198
large amounts of patches to fix the problem. The fixes have resulted in better performance, less code, and a remarkable simplification
199
of this backend. Commits C1039, C1034, C1035, C1006, C999, C905 and previous.
200
</para>
201
</listitem>
202
<listitem>
203
<para>
204
BIND backend gave convincing NXDOMAINS on unloaded zones in some cases. Spotted and fixed by Daniel Bilik in c984.
205
</para>
206
</listitem>
207
<listitem>
208
<para>
209
SOA records in zone transfers sometimes contained the wrong SOA TTL. Spotted by Christian Kuehn, fixed in c902.
210
</para>
211
</listitem>
212
<listitem>
213
<para>
214
PowerDNS could get confused by very high SOA serial numbers. Spotted and fixed by Dan Billik, fixed in c626.
215
</para>
216
</listitem>
217
<listitem>
218
<para>
219
Some versions of FreeBSD perform very strict checks on socket address sizes passed to 'connect', which could lead to problems retrieving zones over AXFR.
220
Fixed in c891.
221
</para>
222
</listitem>
223
<listitem>
224
<para>
225
Some versions of FreeBSD perform very strict checks on IPv6 socket addresses, leading to problems. Discovered by Sten Spans, fixed in c885 and c886.
226
</para>
227
</listitem>
228
<listitem>
229
<para>
230
IXFR requests were not logged properly. Noted by Ralf van der Enden, fixed in c990.
231
</para>
232
</listitem>
233
<listitem>
234
<para>
235
Some NAPTR records needed an additional space character to encode correctly. Spotted by Heinrich Ruthensteiner, fixed in c1029.
236
</para>
237
</listitem>
238
<listitem>
239
<para>
240
Many bugs in the TCP nameserver, leading to a PowerDNS process that did not respond to TCP queries over time. Many fixes provided by
241
Dan Bilik, other problems were fixed by rewriting our TCP handling code. Commits C982 and C980, C950, C924, C889, C874, C869, C685, C684.
242
</para>
243
</listitem>
244
<listitem>
245
<para>
246
Fix crashes on the ARM processor due to alignment errors. Thanks to Sjoerd Simons. Closes Debian bug 397031.
247
</para>
248
</listitem>
249
<listitem>
250
<para>
251
Missing data in generic SQL backends would sometimes lead to faked SOA serial data. Spotted by Leander Lakkas from True. Fix in c866.
252
</para>
253
</listitem>
254
<listitem>
255
<para>
256
When receiving two quick notifications in succession, the packet cache would sometimes "process" the second one, leading PowerDNS to ignore it. Spotted by
257
Dan Bilik, fixed in c686.
258
</para>
259
</listitem>
260
<listitem>
261
<para>
262
Geobackend (by Mark Bergsma) did not properly override the getSOA method, breaking non-overlay operation of this fine backend. The geobackend now also
263
skips '.hidden' configuration files, and now properly disregards empty configuration files. Additionally, the overlapping abilities were improved. Details
264
available in c876, by Mark.
265
</para>
266
</listitem>
267
</itemizedlist>
268
</para>
269
<para>
270
Features:
271
<itemizedlist>
272
<listitem>
273
<para>
274
Thanks to <ulink url="http://www.easydns.com">EasyDNS</ulink>, PowerDNS now supports multiple masters per domain. For configuration
275
details, see <xref linkend="slave">. Implemented in c1018, c1017.
276
</para>
277
</listitem>
278
<listitem>
279
<para>
280
Thanks to <ulink url="http://www.easydns.com">EasyDNS</ulink>, PowerDNS now supports the KEY record type, as well the SPF record. In c976.
281
</para>
282
</listitem>
283
<listitem>
284
<para>
285
Added support for CERT, SSHFP, DNSKEY, DS, NSEC, RRSIG record types, as part of the move to the new DNS parsing/generating code.
286
</para>
287
</listitem>
288
<listitem>
289
<para>
290
Support for the AFSDB record type, as requested by 'Bastian'. Implemented in c978, closing t129.
291
</para>
292
</listitem>
293
<listitem>
294
<para>
295
Support for the MR record type. Implemented in c941 and c1019.
296
</para>
297
</listitem>
298
<listitem>
299
<para>
300
Gsqlite3 backend was added by Antony Lesuisse in c942;
301
</para>
302
</listitem>
303
<listitem>
304
<para>
305
Added the ability to send out light-weight root-referrals that save bandwidth yet still placate mediocre resolver implementations. Implemented in c912,
306
enable with 'root-referral=lean'.
307
</para>
308
</listitem>
309
</itemizedlist>
310
</para>
311
<para>
312
Improvements:
313
<itemizedlist>
314
<listitem>
315
<para>
316
Miscellaneous OpenDBX and LDAP backend improvements by Norbert Sendetzky. Applied in c977 and c1040.
317
</para>
318
</listitem>
319
<listitem>
320
<para>
321
SGML source of the documentation was cleaned up by Ruben Kerkhof in c936.
322
</para>
323
</listitem>
324
<listitem>
325
<para>
326
Speedups in core DNS label processing code. Implemented in c928, c654, c1020.
327
</para>
328
</listitem>
329
<listitem>
330
<para>
331
When communicating with master servers and encountering errors, more useful details are logged. Reported by Stefan Arentz in t137, closed by c1015.
332
</para>
333
</listitem>
334
<listitem>
335
<para>
336
Database errors are now logged with more details. Addressed in c1004.
337
</para>
338
</listitem>
339
<listitem>
340
<para>
341
pdns_control problems are now logged more verbosely. Change in c910.
342
</para>
343
</listitem>
344
<listitem>
345
<para>
346
Erroneous address configuration was logged unclearly. Spotted by River Tarnell, fixed in c888.
347
</para>
348
</listitem>
349
<listitem>
350
<para>
351
Example configuration shipped with PowerDNS was very old. Noted by Leen Besselink, fixed in c946.
352
</para>
353
</listitem>
354
<listitem>
355
<para>
356
PowerDNS neglected to chdir to the root when chrooted. This closes t110, fixed in c944.
357
</para>
358
</listitem>
359
<listitem>
360
<para>
361
Microsoft resolver had problems with responses we generated for CNAMEs pointing out of our bailiwick. Fixed in c983 and expedited by Locaweb.com.br.
362
</para>
363
</listitem>
364
<listitem>
365
<para>
366
Built-in webserver logs errors more verbosely. Closes t82, gixed in c991.
367
</para>
368
</listitem>
369
<listitem>
370
<para>
371
Queries containing '@' no longer flood the logs. Addressed in c1014.
372
</para>
373
</listitem>
374
<listitem>
375
<para>
376
The build process now looks for PostgreSQL in more places. Implemented in c998, closes t90.
377
</para>
378
</listitem>
379
<listitem>
380
<para>
381
Speedups in the BIND backend now mean large installations enjoy startup times up to 30 times faster than with the original BIND nameserver. Many thanks
382
to Massimo Bandinelli.
383
</para>
384
</listitem>
385
<listitem>
386
<para>
387
BIND backend now offers full support for query logging, implemented in c1026, c1029.
388
</para>
389
</listitem>
390
<listitem>
391
<para>
392
BIND backend named.conf parsing is now fully case-insensitive for domain names. This closes Debian bug 406461, fixed in c1027.
393
</para>
394
</listitem>
395
<listitem>
396
<para>
397
IPv6 and IPv4 address parsing routines have been replaced, which should result in prettier output in some cases. c962, c1012 and others.
398
</para>
399
</listitem>
400
<listitem>
401
<para>
402
5 new regression tests have been added to insure old bugs do not return.
403
</para>
404
</listitem>
405
<listitem>
406
<para>
407
Fix small issues with very modern compilers and BOOST snapshots. Noted by Marcus Rueckert, addressed in c954, c964 c965, c1003.
408
</para>
409
</listitem>
410
</itemizedlist>
411
</para>
412
</sect2>
413
<sect2 id="changelog-recursor-3-1-4"><title>Recursor version 3.1.4</title>
414
<para>
415
Released the 13th of November 2006.
416
</para>
417
<para>
418
This release contains almost no new features, but consists mostly of minor and major bug fixes. It also addresses two major security issues, which makes
419
this release a highly recommended upgrade.
420
</para>
421
<para>
422
Security issues:
423
<itemizedlist>
424
<listitem>
425
<para>
426
Large TCP questions followed by garbage could cause the recursor to crash. This critical security issue has been assigned CVE-2006-4251, and is fixed in
427
c915. More information can be found in <xref linkend="powerdns-advisory-2006-01">.
428
</para>
429
</listitem>
430
<listitem>
431
<para>
432
CNAME loops with zero second TTLs could cause crashes in some conditions. These loops could be constructed by malicious parties,
433
making this issue a potential denial of service attack. This security issue has been assigned CVE-2006-4252 and is fixed by c919.
434
More information can be found in <xref linkend="powerdns-advisory-2006-02">. Many thanks to David Gavarret for helping pin down this problem.
435
</para>
436
</listitem>
437
</itemizedlist>
438
</para>
439
<para>
440
Bugs:
441
<itemizedlist>
442
<listitem>
443
<para>
444
On certain error conditions, PowerDNS would neglect to close a socket, which might therefore eventually run out. Spotted by Stefan Schmidt, fixed in commits C892, C897, C899.
445
</para>
446
</listitem>
447
<listitem>
448
<para>
449
Some nameservers (including PowerDNS in rare circumstances) emit a SOA record in the authority section. The recursor mistakenly interpreted this as an
450
authoritative "NXRRSET". Spotted by Bryan Seitz, fixed in c893.
451
</para>
452
</listitem>
453
<listitem>
454
<para>
455
In some circumstances, PowerDNS could end up with a useless (not working, or no longer working) set of nameserver records for a domain. This release contains logic
456
to invalidate such broken NSSETs, without overloading authoritative servers. This problem had previously been spotted by Bryan Seitz, 'Cerb' and Darren Gamble.
457
Invalidations of NSSETs can be plotted using the "nsset-invalidations" metric, available through <command>rec_control get</command>.
458
Implemented in c896 and c901.
459
</para>
460
</listitem>
461
<listitem>
462
<para>
463
PowerDNS could crash while dumping the cache using <command>rec_control dump-cache</command>. Reported by Wouter of WideXS and Stefan Schmidt and many others, fixed in c900.
464
</para>
465
</listitem>
466
<listitem>
467
<para>
468
Under rare circumstances (depleted TCP buffers), PowerDNS might send out incomplete questions to remote servers. Additionally, on big-endian systems (non-Intel and non-AMD
469
generally), sending out large TCP answers questions would not work at all, and possibly crash. Brought to our attention by David Gavarret, fixed in c903.
470
</para>
471
</listitem>
472
<listitem>
473
<para>
474
The recursor contained the potential for a dead-lock processing an invalid domain name. It is not known how this might be triggered,
475
but it has been observed by 'Cerb' on #powerdns. Several dead-locks where PowerDNS consumed all CPU, but did not answer questions,
476
have been reported in the past few months. These might be fixed by c904.
477
</para>
478
</listitem>
479
<listitem>
480
<para>
481
IPv6 'allow-from' matching had problems with the least significant bits, sometimes allowing disallowed addresses, but mostly disallowing allowed addresses. Spotted by Wouter
482
from WideXS, fixed in c916.
483
</para>
484
</listitem>
485
486
</itemizedlist>
487
Improvements:
488
<itemizedlist>
489
<listitem>
490
<para>
491
PowerDNS has support to drop answers from so called 'delegation only' zones. A statistic ("dlg-only-drops") is now available to plot how often this happens. Implemented in c890.
492
</para>
493
</listitem>
494
<listitem>
495
<para>
496
Hint-file parameter was mistakenly named "hints-file" in the documentation. Spotted by my Marco Davids, fixed in c898.
497
</para>
498
</listitem>
499
<listitem>
500
<para>
501
<command>rec_control quit</command> should be near instantaneous now, as it no longer meticulously cleans up memory before exiting. Problem spotted by Darren Gamble, fixed in
502
c914, closing t84.
503
</para>
504
</listitem>
505
<listitem>
506
<para>
507
init.d script no longer refers to the Recursor as the Authoritative Server. Spotted by Wouter of WideXS, fixed in c913.
508
</para>
509
</listitem>
510
<listitem>
511
<para>
512
A potentially serious warning for users of the GNU C Library version 2.5 was fixed. Spotted by Marcus Rueckert, fixed in c920.
513
</para>
514
</listitem>
515
</itemizedlist>
516
</para>
517
</sect2>
518
519
<sect2 id="changelog-recursor-3-1-3"><title>Recursor version 3.1.3</title>
520
<para>
521
Released the 12th of September 2006.
522
</para>
523
<para>
524
Compared to 3.1.2, this release again consists of a number of mostly minor bug fixes, and some slight improvements.
525
</para>
526
<para>
527
Many thanks are again due to Darren Gamble who together with his team has discovered many misconfigured domains that do work
528
with some other name servers. DNS has long been tolerant of misconfigurations, PowerDNS intends to uphold that tradition. Almost all of
529
the domains found by Darren now work as well in PowerDNS as in other name server implementations.
530
</para>
531
<para>
532
Thanks to some recent migrations, this release, or something very close to it, is powering over 40 million internet connections that
533
we know of. We appreciate hearing about succesful as well as unsuccesful migrations, please feel free to notify pdns.bd@powerdns.com of your
534
experiences, good or bad.
535
</para>
536
<para>
537
Bug-fixes:
538
<itemizedlist>
539
<listitem>
540
<para>
541
The MThread default stack size was too small, which led to problems, mostly on 64-bit platforms. This stack size is now configurable
542
using the <command>stack-size</command> setting should our estimate be off. Discovered by Darren Gamble, Sten Spans and a number of others.
543
Fixed in c868.
544
</para>
545
</listitem>
546
<listitem>
547
<para>
548
Plug a small memory leak discovered by Kai and Darren Gamble, fixed in c870.
549
</para>
550
</listitem>
551
<listitem>
552
<para>
553
Switch from the excellent nedmalloc to dlmalloc, based on advice by the nedmalloc author. Nedmalloc is optimised for multithreaded
554
operation, whereas the PowerDNS recursor is single threaded. The version of nedmalloc shipped contained a number of possible bugs,
555
which are probably resolved by moving to dlmalloc. Some reported crashes on hitting 2G of allocated memory on 64 bit systems might
556
be solved by this switch, which should also increase performance. See c873 for details.
557
</para>
558
</listitem>
559
</itemizedlist>
560
</para>
561
<para>
562
Improvements:
563
<itemizedlist>
564
<listitem>
565
<para>
566
The cache is now explicitly aware of the difference between authoritative and unauthoritative data, allowing it to deal
567
with some domains that have different data in the parent zone than in the authoritative zone. Patch in c867.
568
</para>
569
</listitem>
570
<listitem>
571
<para>
572
No longer try to parse DNS updates as if they were queries. Discovered and fixed by Jan Gyselinck, fix in c871.
573
</para>
574
</listitem>
575
<listitem>
576
<para>
577
Rebalance logging priorities for less log cluttering and add IP address to a remote server error message.
578
Noticed and fixed by Jan Gyselinck (c877).
579
</para>
580
</listitem>
581
<listitem>
582
<para>
583
Add <command>logging-facility</command> setting, allowing syslog to send PowerDNS logging to a separate file. Added in c871.
584
</para>
585
</listitem>
586
</itemizedlist>
587
</para>
588
</sect2>
589
<sect2 id="changelog-recursor-3-1-2"><title>Recursor version 3.1.2</title>
590
<para>
591
Released Monday 26th of June 2006.
592
</para>
593
<para>
594
Compared to 3.1.1, this release consists almost exclusively of bug-fixes and speedups. A quick update is recommended, as some of the bugs
595
impact operators of authoritative zones on the internet. This version has been tested by some of the largest internet providers on the planet,
596
and is expected to perform well for everybody.
597
</para>
598
<para>
599
Many thanks are due to Darren Gamble, Stefan Schmidt and Bryan Seitz who all provided excellent feedback based on their large-scale
600
tests of the recursor.
601
</para>
602
<para>
603
Bug-fixes:
604
<itemizedlist>
605
<listitem>
606
<para>
607
Internal authoritative server did not differentiate between 'NXDOMAIN' and 'NXRRSET', in other words, it would answer
608
'no such host' when an AAAA query came in for a domain that did exist, but did not have an AAAA record. This only affects
609
users with <command>auth-zones</command> configured. Discovered by Bryan Seitz, fixed in c848.
610
</para>
611
</listitem>
612
<listitem>
613
<para>
614
ANY queries for hosts where nothing was present in the cache would not work. This did not cause real problems as ANY queries are
615
not reliable (by design) for anything other than debugging, but did slow down the nameserver and cause unnecessary load on remote
616
nameservers. Fixed in c854.
617
</para>
618
</listitem>
619
<listitem>
620
<para>
621
When exceeding the configured maximum amount of TCP sessions, TCP support would break and the nameserver would waste CPU trying to accept TCP
622
connections on UDP ports. Noted by Bryan Seitz, fixed in c849.
623
</para>
624
</listitem>
625
<listitem>
626
<para>
627
DNS queries come in two flavours: recursion desired and non-recursion desired. The latter is not very useful for a recursor, but is
628
sometimes (erroneously) used by monitoring software or loadbalancers to detect nameserver availability. A non-rd query would not only not recurse,
629
but also not query authoritative zones, which is confusing. Fixed in c847.
630
</para>
631
</listitem>
632
<listitem>
633
<para>
634
Non-standard DNS TCP queries, that did occur however, could drive the recursor to 100% CPU usage for extended periods of time. This did not disrupt service
635
immediately, but does waste a lot of CPU, possibly exhausting resources. Discovered by Bryan Seitz, fixed in c858, which is post-3.1.2-rc1.
636
</para>
637
</listitem>
638
<listitem>
639
<para>
640
The PowerDNS recursor did not honour the rare but standardised 'ANY' query class (normally 'ANY' refers to the query type, not class), upsetting the Wildfire
641
Jabber server. Discovered and debugged by Daniel Nauck, fixed in c859, which is post-3.1.2-rc1.
642
</para>
643
</listitem>
644
<listitem>
645
<para>
646
Everybody's favorite, when starting up under high load, a bogus line of statistics was sometimes logged. Fixed in c851.
647
</para>
648
</listitem>
649
<listitem>
650
<para>
651
Remove some spurious debugging output on dropping a packet by an unauthorized host. Discovered by Kai. Fixed in c854.
652
</para>
653
</listitem>
654
</itemizedlist>
655
</para>
656
<para>
657
Improvements:
658
<itemizedlist>
659
<listitem>
660
<para>
661
Misconfigured domains, with a broken nameserver in the parent zone, should now work better. Changes motivated and suggested by
662
Darren Gamble. This makes PowerDNS more compliant with RFC 2181 by making it prefer authoritative data over non-authoritative data.
663
Implemented in c856.
664
</para>
665
</listitem>
666
<listitem>
667
<para>
668
PowerDNS can now listen on multiple ports, using the <command>local-address</command> setting. Added in c845.
669
</para>
670
</listitem>
671
<listitem>
672
<para>
673
A number of speedups which should have a noticeable impact, implemented in commits C850, C852, C853, C855
674
</para>
675
</listitem>
676
<listitem>
677
<para>
678
The recursor now works around an issue with the Linux kernel 2.6.8, as shipped by Debian. Fixed by Christof Meerwald in c860, which is post 3.1.2-rc1.
679
</para>
680
</listitem>
681
</itemizedlist>
682
</para>
683
</sect2>
684
<sect2 id="changelog-recursor-3-1-1"><title>Recursor version 3.1.1</title>
685
<para>
686
<warning>
687
<para>
688
3.1.1 is identical to 3.1 except for a bug in the packet chaining code which would mainly manifest itself for IPv6 enabled Konqueror
689
users with very fast connections to their PowerDNS installation. However, all 3.1 users are urged to upgrade to 3.1.1.
690
Many thanks to Alessandro Bono for his quick aid in solving this problem.
691
</para>
692
</warning>
693
</para>
694
<para>
695
Released on the 23rd of May 2006. Many thanks are due to the operators of some of the largest internet access providers in the world,
696
each having many millions of customers, who have tested the various 3.1 pre-releases for suitability. They have uncovered and helped
697
fix bugs that could impact us all, but are only (quickly) noticeable with such vast amounts of DNS traffic.
698
</para>
699
<para>
700
After version 3.0.1 has proved to hold up very well under tremendous loads, 3.1 adds important new features:
701
<itemizedlist>
702
<listitem>
703
<para>
704
Ability to serve authoritative data from 'BIND' style zone files (using <command>auth-zones</command> statement).
705
</para>
706
</listitem>
707
<listitem>
708
<para>
709
Ability to forward domains so configured to external servers (using <command>forward-zones</command>).
710
</para>
711
</listitem>
712
<listitem>
713
<para>
714
Possibility of 'serving' the contents of <filename>/etc/hosts</filename> over DNS, which is very well
715
suited to simple domestic router/DNS setups. Enabled using <command>export-etc-hosts</command>.
716
</para>
717
</listitem>
718
<listitem>
719
<para>
720
As recommended by recent standards documents, the PowerDNS recursor is now authoritative for RFC-1918 private IP space
721
zones by default (suggested by Paul Vixie).
722
</para>
723
</listitem>
724
<listitem>
725
<para>
726
Full outgoing IPv6 support (off by default) with IPv6 servers getting equal treatment with IPv4, nameserver
727
addresses are chosen based on average response speed, irrespective of protocol.
728
</para>
729
</listitem>
730
<listitem>
731
<para>
732
Initial Windows support, including running as a service ('NET START "POWERDNS RECURSOR"'). <command>rec_channel</command> is still missing,
733
the rest should work. Performance appears to be below that of the UNIX versions, this situation is expected to improve.
734
</para>
735
</listitem>
736
</itemizedlist>
737
</para>
738
<para>
739
Bug fixes:
740
<itemizedlist>
741
<listitem>
742
<para>
743
No longer send out SRV and MX record priorities as zero on big-endian platforms (UltraSPARC). Discovered by Eric Sproul, fixed in c773.
744
</para>
745
</listitem>
746
<listitem>
747
<para>
748
SRV records need additional processing, especially in an Active Directory setting. Reported by Kenneth Marshall, fixed in c774.
749
</para>
750
</listitem>
751
<listitem>
752
<para>
753
The root-records were not being refreshed, which could lead to problems under inconceivable conditions. Fixed in c780.
754
</para>
755
</listitem>
756
<listitem>
757
<para>
758
Fix resolving domain names for nameservers with multiple IP addresses, with one of these addresses being lame. Other nameserver implementations
759
were also unable to resolve these domains, so not a big bug. Fixed in c780.
760
</para>
761
</listitem>
762
<listitem>
763
<para>
764
For a period of 5 minutes after expiring a negative cache entry, the domain would not be re-cached negatively, leading to a lot of duplicate
765
outgoing queries for this short period. This fix has raised the average cache hit rate of the recursor by a few percent. Fixed in c783.
766
</para>
767
</listitem>
768
769
<listitem>
770
<para>
771
Query throttling was not aggressive enough and not all sorts of queries were throttled. Implemented in c786.
772
</para>
773
</listitem>
774
775
<listitem>
776
<para>
777
Fix possible crash during startup when parsing empty configuration lines (c807).
778
</para>
779
</listitem>
780
<listitem>
781
<para>
782
Fix possible crash when the first query after wiping a cache entry was for the just deleted entry. Rare in production servers. Fixed in c820.
783
</para>
784
</listitem>
785
<listitem>
786
<para>
787
Recursor would send out differing TTLs when receiving a misconfigured, standards violating, RRSET with different TTLs. Implement fix as mandated by
788
RFC 2181, paragraph 5.2. Reported by Stephen Harker (c819).
789
</para>
790
</listitem>
791
<listitem>
792
<para>
793
The <command>top-remotes</command> would list remotes duplicately, once per source port. Discovered by Jorn Ekkelenkamp, fixed in c827, which is post 3.1-pre1.
794
</para>
795
</listitem>
796
<listitem>
797
<para>
798
Default <command>allow-from</command> allowed queries from fe80::/16, corrected to fe80::/10. Spotted by Niels Bakker, fixed in c829, which is post 3.1-pre1.
799
</para>
800
</listitem>
801
<listitem>
802
<para>
803
While PowerDNS blocks failing queries quickly, multiple packets could briefly be in flight for the same domain and nameserver. This situation is now
804
explicitly detected and queries are chained to identical queries already in flight. Fixed in c833 and c834, post 3.1-pre1.
805
</para>
806
</listitem>
807
</itemizedlist>
808
</para>
809
<para>
810
Improvements:
811
<itemizedlist>
812
<listitem>
813
<para>
814
ANY queries are now implemented as in other nameserver implementations, leading to a decrease in outgoing queries. The RFCs are not very
815
clear on desired behaviour, what is implemented now saves bandwidth and CPU and brings us in line with existing practice. Previously
816
ANY queries were not cached by the PowerDNS recursor. Implemented in c784.
817
</para>
818
</listitem>
819
<listitem>
820
<para>
821
<command>rec_control</command> was very sparse in its error reporting, and user unfriendly as well. Reported by Erik Bos, fixed in c818 and c820.
822
</para>
823
</listitem>
824
<listitem>
825
<para>
826
IPv6 addresses were printed in a non-standard way, fixed in c788.
827
</para>
828
</listitem>
829
<listitem>
830
<para>
831
TTLs of records are now capped at two weeks, c820.
832
</para>
833
</listitem>
834
<listitem>
835
<para>
836
<command>allow-from</command> IPv4 netmasks now automatically work for IP4-to-IPv6 mapper IPv4 addresses, which appear when running on the wildcard
837
<command>::</command> IPv6 address. Lack of feature noted by Marcus 'darix' Rueckert. Fixed in c826, which is post 3.1-pre1.
838
</para>
839
</listitem>
840
<listitem>
841
<para>
842
Errors before daemonizing are now also sent to syslog. Suggested by Marcus 'darix' Rueckert. Fixed in c825, which is post 3.1-pre1.
843
</para>
844
</listitem>
845
<listitem>
846
<para>
847
When launching without any form of configured network connectivity, all root-servers would be cached as 'down' for some time. Detect this special case
848
and treat it as a resource-constraint, which is not accounted against specific nameservers. Spotted by Seth Arnold, fixed in c835, which is post 3.1-pre1.
849
</para>
850
</listitem>
851
<listitem>
852
<para>
853
The recursor now does not allow authoritative servers to keep supplying its own NS records into perpetuity, which causes problems
854
when a domain is redelegated but the old authorative servers are not updated to this effect. Noticed and explained at length by Darren
855
Gamble of Shaw Communications, addressed by c837, which is post 3.1-pre2.
856
</para>
857
</listitem>
858
<listitem>
859
<para>
860
Some operators may want to follow RFC 2181 paragraph 5.2 and 5.4. This harms performance and does not solve any real problem,
861
but does make PowerDNS more compliant. If you want this, enable <command>auth-can-lower-ttl</command>. Implemented in c838, which is
862
post 3.1-pre2.
863
</para>
864
</listitem>
865
</itemizedlist>
866
</para>
867
</sect2>
868
<sect2 id="changelog-recursor-3-0-1"><title>Recursor version 3.0.1</title>
869
<para>
870
Released 25th of April 2006, <ulink url="http://www.powerdns.com/en/downloads.aspx">download</ulink>.
871
</para>
872
<para>
873
This release consists of nothing but tiny fixes to 3.0, including one with security implications. An upgrade is highly recommended.
874
</para>
875
<para>
876
<itemizedlist>
877
<listitem>
878
<para>
879
Compilation used both <filename>cc</filename> and <filename>gcc</filename>, leading to the possibility of compiling with different compiler versions (c766).
880
</para>
881
</listitem>
882
<listitem>
883
<para>
884
<command>rec_control</command> would leave files named <filename>lsockXXXXXX</filename> around in the configured socket-dir. Operators
885
may wish to remove these files from their socket-dir (often <filename>/var/run</filename>), quite a few might have accumulated already (c767).
886
</para>
887
</listitem>
888
889
<listitem>
890
<para>
891
Certain malformed packets could crash the recursor. As far as we can determine these packets could only lead to a crash,
892
but as always, there are no guarantees. A quick upgrade is highly recommended (commits C760, C761). Reported by David Gavarret.
893
</para>
894
</listitem>
895
896
<listitem>
897
<para>
898
Recursor would not distinguish between NXDOMAIN and NXRRSET (c756). Reported and debugged by Jorn Ekkelenkamp.
899
</para>
900
</listitem>
901
<listitem>
902
<para>
903
Some error messages and trace logging statements were improved (commits C756, C758, C759).
904
</para>
905
</listitem>
906
<listitem>
907
<para>
908
stderr was closed during daemonizing, but not dupped to /dev/null, leading to slight chance of odd behaviour on reporting errors (c757)
909
</para>
910
</listitem>
911
</itemizedlist>
912
Operating system specific fixes:
913
<itemizedlist>
914
<listitem>
915
<para>
916
The stock Debian sarge Linux kernel, 2.6.8, claims to support epoll but fails at runtime. The epoll self-testing code has been improved,
917
and PowerDNS will fall back to a select based multiplexer if needed (c758) Reported by Michiel van Es.
918
</para>
919
</listitem>
920
<listitem>
921
<para>
922
Solaris 8 compilation and runtime issues were addressed. See the README for details (c765). Reported by Juergen Georgi and Kenneth Marshall.
923
</para>
924
</listitem>
925
<listitem>
926
<para>
927
Solaris 10 x86_64 compilation issues were addressed (c755). Reported and debugged by Eric Sproul.
928
</para>
929
</listitem>
930
</itemizedlist>
931
</para>
932
</sect2>
933
<sect2 id="changelog-recursor-3-0"><title>Recursor version 3.0</title>
934
<para>
935
Released 20th of April 2006, <ulink url="http://www.powerdns.com/en/downloads.aspx">download</ulink>.
936
</para>
937
<para>
938
This is the first separate release of the PowerDNS Recursor. There are many reasons for this, one of the most important ones is that
939
previously we could only do a release when both the recursor and the authoritative nameserver were fully tested and in good shape. The split
940
allows us to release new versions when each part is ready.
941
</para>
942
<para>
943
Now for the real news. This version of the PowerDNS recursor powers the network access of over two million internet connections. Two large
944
access providers have been running pre-releases of 3.0 for the past few weeks and results are good. Furthermore, the various pre-releases
945
have been tested nearly non-stop with DNS traffic replayed at 3000 queries/second.
946
</para>
947
<para>
948
As expected, the 2 million househoulds shook out some very rare bugs. But even a rare bug happens once in a while when there are this many users.
949
</para>
950
<para>
951
We consider this version of the PowerDNS recursor to be the most advanced resolver publicly available. Given current levels of spam, phishing
952
and other forms of internet crime we think no recursor should offer less than the best in spoofing protection. We urge all
953
operators of resolvers without proper spoofing countermeasures to consider PowerDNS, as it is a Better Internet Nameserver Daemon.
954
</para>
955
<para>
956
A good article on DNS spoofing can be found <ulink url="http://www.securesphere.net/download/papers/dnsspoof.htm">here</ulink>. Some
957
more information, based on a previous version of PowerDNS, can be found on the
958
<ulink url="http://blog.netherlabs.nl/articles/2006/04/14/holy-cow-1-3-million-additional-ip-addresses-served-by-powerdns">PowerDNS development blog</ulink>.
959
</para>
960
<para>
961
<warning>
962
<para>
963
Because of recent DNS based denial of service attacks, running an open recursor has become a security risk. Therefore, unless configured otherwise
964
this version of PowerDNS will only listen on localhost, which means it does not resolve for hosts on your network.
965
To fix, configure the <command>local-address</command> setting with all addresses you want to listen on. Additionally, by default
966
service is restricted to RFC 1918 private IP addresses. Use <command>allow-from</command> to selectively open up the recursor
967
for your own network. See <xref linkend="recursor-settings"> for details.
968
</para>
969
</warning>
970
</para>
971
<para>
972
Important new features of the PowerDNS recursor 3.0:
973
<itemizedlist>
974
<listitem>
975
<para>
976
Best spoofing protection and detection we know of. Not only is spoofing made harder by using a new network address for each query,
977
PowerDNS detects when an attempt is made to spoof it, and temporarily ignores the data. For details, see <xref linkend="anti-spoofing">.
978
</para>
979
</listitem>
980
<listitem>
981
<para>
982
First nameserver to benefit from epoll/kqueue/Solaris completion ports event reporting framework, for stellar performance.
983
</para>
984
</listitem>
985
<listitem>
986
<para>
987
Best statistics of any recursing nameserver we know of, see <xref linkend="recursor-stats">.
988
</para>
989
</listitem>
990
<listitem>
991
<para>
992
Last-recently-used based cache cleanup algorithm, keeping the 'best' records in memory
993
</para>
994
</listitem>
995
<listitem>
996
<para>
997
First class Solaris support, built on a 'try and buy' Sun CoolThreads T 2000.
998
</para>
999
</listitem>
1000
<listitem>
1001
<para>
1002
Full IPv6 support, implemented natively.
1003
</para>
1004
</listitem>
1005
<listitem>
1006
<para>
1007
Access filtering, both for IPv4 and IPv6.
1008
</para>
1009
</listitem>
1010
<listitem>
1011
<para>
1012
Experimental SMP support for nearly double performance. See <xref linkend="recursor-performance">.
1013
</para>
1014
</itemizedlist>
1015
</para>
1016
<para>
1017
Many people helped package and test this release. Jorn Ekkelenkamp of ISP-Services helped find the '8000 SOAs' bug and spotted
1018
many other oddities and <ulink url="http://www.xs4all.nl">XS4ALL</ulink> internet funded a lot of the recent development.
1019
Joaquín M López Muñoz of the boost::multi_index_container was again of great help.
1020
</para>
1021
</sect2>
84
1022
<sect2 id="changelog-2-9-20"><title>Version 2.9.20</title>
85
1023
<para>
86
Released the 15th of March 2005
1024
Released the 15th of March 2006
87
1025
</para>
88
1026
<para>
89
1027
Besides adding OpenDBX, this release is mostly about fixing problems and speeding up the recursor. This release has been made possible by
784
1722
<itemizedlist>
785
1723
<listitem>
786
1724
<para>
787
Reported version can be changed, or removed - see the "version-string" setting.
1725
Reported version can be changed, or removed - see the "version-string" setting.
788
1726
</para>
789
1727
</listitem>
790
1728
<listitem>
796
1734
</itemizedlist>
797
1735
</para>
798
1736
<para>
799
Bug fixes:
800
<para>
1737
Bug fixes:
801
1738
<itemizedlist>
802
1739
<listitem>
803
1740
<para>
1277
2214
</listitem>
1278
2215
<listitem>
1279
2216
<para>
1280
delegation-only, a Verisign special. See <xref linkend="verisign">.
2217
delegation-only, a Verisign special.
1281
2218
</para>
1282
2219
</listitem>
1283
2220
<listitem>
1332
2269
<para>
1333
2270
gpgsql no longer reports as gmysql (Sherwin Daganoto)
1334
2271
</para>
2272
</listitem>
1335
2273
<listitem>
1336
2274
<para>
1337
2275
SRV would not be parsed right from disk (Christof Meerwald)
1375
2313
<listitem>
1376
2314
<para>
1377
2315
Cleanups by Norbert: getAuth moved to chopOff, arguments::contains massive cleanup, more.
2316
</para>
1378
2317
</listitem>
1379
2318
</itemizedlist>
2319
</para>
1380
2320
</sect2>
1381
2321
1382
2322
<sect2 id="changelog-2-9-11"><title>Version 2.9.11</title>
1383
2323
<para>
1384
2324
Yet another iteration, hopefully this will be the last silly release.
2325
</para>
1385
2326
<para>
1386
2327
<warning>
1387
2328
<para>
1469
2410
LDAP: added support for scoped searches (Norbert Sendetzky)
1470
2411
</para>
1471
2412
</listitem>
1472
</itemizedlist>
1473
</sect2>
2413
</itemizedlist>
2414
</para>
2415
</sect2>
1474
2416
<sect2 id="changelog-2-9-8"><title>Version 2.9.8</title>
1475
2417
<para>
1476
2418
Queen's day release! 30th of April 2003.
1709
2651
this issue. We hope to resolve it soon.
1710
2652
</para>
1711
2653
</warning>
2654
</para>
1712
2655
<para>
1713
2656
<itemizedlist>
1714
2657
<listitem>
2464
3407
doing. Stability is expected to return with 2.9.1, as are the binary builds.
2465
3408
</para>
2466
3409
<para>
2467
<itemizedlist>
2468
<listitem>
2469
<para>
2470
License changed to the GNU General Public License version 2.
2471
</para>
2472
</listitem>
2473
<listitem>
2474
<para>
3410
<itemizedlist>
3411
<listitem>
3412
<para>
3413
License changed to the GNU General Public License version 2.
3414
</para>
3415
</listitem>
3416
<listitem>
3417
<para>
2475
3418
Cleanups by Erik Bos @ xs4all.
2476
</para>
2477
</listitem>
2478
<listitem>
2479
<para>
3419
</para>
3420
</listitem>
3421
<listitem>
3422
<para>
2480
3423
Build improvements by Wichert Akkerman
2481
</para>
2482
</listitem>
2483
<listitem>
2484
<para>
3424
</para>
3425
</listitem>
3426
<listitem>
3427
<para>
2485
3428
Lots of work on the build system, entirely revamped. By PowerDNS.
3429
</para>
3430
</listitem>
3431
</itemizedlist>
2486
3432
</para>
2487
</listitem>
2488
</itemizedlist>
2489
</sect2>
3433
</sect2>
2490
3434
2491
3435
<sect2 id="changelog-2-8"><title>Version 2.8</title>
2492
3436
<para>
2934
3878
</para>
2935
3879
</listitem>
2936
3880
</itemizedlist>
3881
</para>
2937
3882
<para>
2938
3883
Documentation: added details for <command>strict-rfc-axfrs</command>. This feature can be used if very old clients need to be able
2939
3884
to do zone transfers with PDNS. Very slow.
3521
4466
</para>
3522
4467
</listitem>
3523
4468
</itemizedlist>
4469
</para>
4470
</sect2>
3524
4471
3525
</sect2>
3526
4472
<sect2 id="changelog-1-99-11"><title>Version 1.99.11 Prerelease</title>
3527
4473
<para>
3528
4474
This release is important because it is the first release which is accompanied by an Open Source Backend Development Kit, allowing external
4404
5350
Stability may be an issue as well as performance. This version has a tendency to log a bit too much which slows
4405
5351
the nameserver down a lot.
4406
5352
</para>
4407
<sect3><title>Known bugs</title>
5353
<sect3>
5354
<title>Known bugs</title>
4408
5355
<para>
4409
5356
Decreasing a ringbuffer on the website is a sure way to crash the daemon. Zone2sql, while improved, still
4410
5357
has problems with a zone in the following format:
4418
5365
</para>
4419
5366
<para>
4420
5367
Zone2sql does not close filedescriptors.
4421
<para>
5368
</para>
4422
5369
4423
5370
<para>
4424
5371
FreeBSD version does not stop when requested via the init.d script.
4425
<para>
5372
</para>
4426
5373
4427
5374
</sect3>
4428
5375
<sect3><title>Missing features</title>
4486
5433
</sect1>
4487
5434
<sect1 id="security-policy"><title>Security</title>
4488
5435
<para>
4489
As of the 16th of July 2005, no actual security problems with PowerDNS 2.9.18 or later are known about. This page
5436
As of the 11th of November 2006, no actual security problems with PowerDNS 2.9.18, Recursor 3.1.4, or later are known about. This page
4490
5437
will be updated with all bugs which are deemed to be security problems, or could conceivably lead to those. Any such notifications
4491
5438
will also be sent to all PowerDNS mailinglists.
4492
5439
</para>
4493
5440
<para>
5441
Version 3.1.3 and earlier of the PowerDNS recursor contain two security issues, both of which can lead to a denial of service, both of which can be triggered
5442
by remote users. One of the issues might lead be exploited and lead to a system compromise. For more detail, see <xref linkend="powerdns-advisory-2006-01"> and
5443
<xref linkend="powerdns-advisory-2006-02">.
5444
</para>
5445
<para>
5446
Version 3.0 of the PowerDNS recursor contains a denial of service bug which can be exploited remotely. This bug, which we believe to only lead to a crash,
5447
has been fixed in 3.0.1. There are no guarantees however, so an upgrade from 3.0 is highly recommended.
5448
</para>
5449
<para>
4494
5450
All versions of PowerDNS before 2.9.18 contain the following two bugs, which only apply to installations running with the LDAP backend, or installations providing recursion
4495
5451
to a limited range of IP addresses. If any of these apply to you, an upgrade is highly advised:
4496
5452
<itemizedlist>
4523
5479
This license is included in the distribution and in this documentation, see <xref linkend="license">.
4524
5480
</para>
4525
5481
</sect1>
4526
5482
<sect1 id="powerdns-advisory-2006-01">
5483
<title>PowerDNS Security Advisory 2006-01: Malformed TCP queries can lead to a buffer overflow which might be exploitable</title>
5484
<para>
5485
<table>
5486
<title>PowerDNS Security Advisory</title>
5487
<tgroup cols=2>
5488
<tbody>
5489
<row>
5490
<entry>
5491
CVE
5492
</entry>
5493
<entry>
5494
CVE-2006-4251
5495
</entry>
5496
</row>
5497
<row>
5498
<entry>
5499
Date
5500
</entry>
5501
<entry>
5502
13th of November 2006
5503
</entry>
5504
</row>
5505
<row>
5506
<entry>
5507
Affects
5508
</entry>
5509
<entry>
5510
PowerDNS Recursor versions 3.1.3 and earlier, on all operating systems.
5511
</entry>
5512
</row>
5513
<row>
5514
<entry>
5515
Not affected
5516
</entry>
5517
<entry>
5518
No versions of the PowerDNS Authoritative Server ('pdns_server') are affected.
5519
</entry>
5520
</row>
5521
<row>
5522
<entry>
5523
Severity
5524
</entry>
5525
<entry>
5526
Critical
5527
</entry>
5528
</row>
5529
<row>
5530
<entry>
5531
Impact
5532
</entry>
5533
<entry>
5534
Potential remote system compromise.
5535
</entry>
5536
</row>
5537
<row>
5538
<entry>
5539
Exploit
5540
</entry>
5541
<entry>
5542
As far as we know, no exploit is available as of 11th of November 2006.
5543
</entry>
5544
</row>
5545
<row>
5546
<entry>
5547
Solution
5548
</entry>
5549
<entry>
5550
Upgrade to PowerDNS Recursor 3.1.4, or apply the patches referred below and recompile
5551
</entry>
5552
</row>
5553
<row>
5554
<entry>
5555
Workaround
5556
</entry>
5557
<entry>
5558
Disable TCP access to the Recursor. This will have slight operational impact, but it is likely that this will not lead
5559
to meaningful degradation of service. Disabling access is best performed at packet level, either by configuring a firewall, or
5560
instructing the host operating system to drop TCP connections to port 53.
5561
Additionally, exposure can be limited by configuring the <command>allow-from</command> setting so only trusted users
5562
can query your nameserver.
5563
</entry>
5564
</row>
5565
</tgroup>
5566
</table>
5567
</para>
5568
<para>
5569
PowerDNS Recursor 3.1.3 and previous miscalculate the length of incoming TCP DNS queries, and will attempt to read up to 4 gigabytes of query
5570
into a 65535 byte buffer.
5571
</para>
5572
<para>
5573
We have not verified if this problem might actually lead to a system compromise, but are acting on the assumption that it might.
5574
</para>
5575
<para>
5576
For distributors, a minimal patch is available on <ulink url="http://wiki.powerdns.com/cgi-bin/trac.fcgi/changeset/915">the PowerDNS wiki</ulink>.
5577
Additionally, those shipping very old versions of the PowerDNS Recursor might benefit from this <ulink url="http://ds9a.nl/tmp/cve-2006-4251.patch">
5578
patch</ulink>.
5579
</para>
5580
<para>
5581
The impact of these and other security problems can be lessened by considering the advice in <xref linkend="security">.
5582
</para>
5583
</sect1>
5584
<sect1 id="powerdns-advisory-2006-02">
5585
<title>PowerDNS Security Advisory 2006-02: Zero second CNAME TTLs can make PowerDNS exhaust allocated stack space, and crash</title>
5586
<para>
5587
<table>
5588
<title>PowerDNS Security Advisory</title>
5589
<tgroup cols=2>
5590
<tbody>
5591
<row>
5592
<entry>
5593
CVE
5594
</entry>
5595
<entry>
5596
CVE-2006-4252
5597
</entry>
5598
</row>
5599
<row>
5600
<entry>
5601
Date
5602
</entry>
5603
<entry>
5604
13th of November 2006
5605
</entry>
5606
</row>
5607
<row>
5608
<entry>
5609
Affects
5610
</entry>
5611
<entry>
5612
PowerDNS Recursor versions 3.1.3 and earlier, on all operating systems.
5613
</entry>
5614
</row>
5615
<row>
5616
<entry>
5617
Not affected
5618
</entry>
5619
<entry>
5620
No versions of the PowerDNS Authoritative Server ('pdns_server') are affected.
5621
</entry>
5622
</row>
5623
<row>
5624
<entry>
5625
Severity
5626
</entry>
5627
<entry>
5628
Moderate
5629
</entry>
5630
</row>
5631
<row>
5632
<entry>
5633
Impact
5634
</entry>
5635
<entry>
5636
Denial of service
5637
</entry>
5638
</row>
5639
<row>
5640
<entry>
5641
Exploit
5642
</entry>
5643
<entry>
5644
This problem can be triggered by sending queries for specifically configured domains
5645
</entry>
5646
</row>
5647
<row>
5648
<entry>
5649
Solution
5650
</entry>
5651
<entry>
5652
Upgrade to PowerDNS Recursor 3.1.4, or apply c919.
5653
</entry>
5654
</row>
5655
<row>
5656
<entry>
5657
Workaround
5658
</entry>
5659
<entry>
5660
None known. Exposure can be limited by configuring the <command>allow-from</command> setting so only trusted users
5661
can query your nameserver.
5662
</entry>
5663
</row>
5664
</tgroup>
5665
</table>
5666
</para>
5667
<para>
5668
PowerDNS would recurse endlessly on encountering a CNAME loop consisting entirely of zero second CNAME records, eventually exceeding resources and crashing.
5669
</para>
5670
</sect1>
4527
5671
<sect1 id="thanks-to"><title>Acknowledgements</title>
4528
5672
<para>
4529
5673
PowerDNS is grateful for the help of the following people or institutions:
4545
5689
<para>
4546
5690
(these people don't share the blame for any errors or mistakes in powerdns - those are all ours)
4547
5691
</para>
4548
</Chapter>
5692
</sect1>
5693
</Chapter>
4549
5694
4550
5695
<Chapter id="installing-on-unix">
4551
5696
<Title>Installing on Unix</Title>
4991
6136
create table domains (
4992
6137
id INT auto_increment,
4993
6138
name VARCHAR(255) NOT NULL,
4994
master VARCHAR(20) DEFAULT NULL,
6139
master VARCHAR(128) DEFAULT NULL,
4995
6140
last_check INT DEFAULT NULL,
4996
6141
type VARCHAR(6) NOT NULL,
4997
6142
notified_serial INT DEFAULT NULL,
5140
6285
</listitem>
5141
6286
</varlistentry>
5142
6287
</variablelist>
6288
</para>
5143
6289
</sect2>
5144
6290
</sect1>
5145
6291
</chapter>
5367
6513
5368
6514
</screen>
5369
6515
</para>
6516
</sect1>
5370
6517
<sect1 id="syslog"><title>Operational logging using syslog</title>
5371
6518
<para>(<command>logging-facility</command> is available from 1.99.10 and onwards)</para>
5372
6519
<para>
5414
6561
<sect1 id="settings"><title>Settings</title>
5415
6562
<para>PDNS has several options to easily allow it to run more securely. Most notable are the <command>chroot</command>,
5416
6563
<command>setuid</command> and <command>setgid</command> options which can be specified.</para>
5417
6564
<para>
6565
For additional information on PowerDNS security, PowerDNS security incidents and PowerDNS security policy, see <xref linkend="security-policy">.
6566
</para>
5418
6567
<sect2><title>Running as a less privileged identity</title>
5419
6568
<para>
5420
6569
By specifying <command>setuid</command> and <command>setgid</command>, PDNS changes to this identity shortly after
5426
6575
Both these parameters can be specified either numerically or as real names.
5427
6576
You should set these parameters immediately if they are not set!
5428
6577
</para>
6578
</sect2>
5429
6579
<sect2><title>Jailing the process in a chroot</title>
5430
6580
<para>
5431
6581
The <command>chroot</command> option secures PDNS to its own directory so that even if it should become compromised and
5589
6739
<para>
5590
6740
The size of the packetcache can be observed with <command>/etc/init.d/pdns show packetcache-size</command>
5591
6741
</para>
5592
</sect1>
5593
<sect1 id="querycache"><title>Query Cache</title>
6742
</sect2>
6743
<sect2 id="querycache"><title>Query Cache</title>
5594
6744
<para>
5595
6745
Besides entire packets, PDNS can also cache individual backend queries. Each DNS query leads to a number of backend queries,
5596
6746
the most obvious additional backend query is the check for a possible CNAME. So, when a query comes in for the 'A' record for
5614
6764
but that the Packet Cache also saves a lot of CPU because 0 internal processing is done when answering a question from the
5615
6765
Packet Cache.
5616
6766
</para>
5617
</sect1>
6767
</sect2>
6768
</sect1>
5618
6769
</chapter>
5619
6770
<chapter id="migration"><title>Migrating to PDNS</title>
5620
6771
<para>
5624
6775
<term>PDNS does not operate as a 'slave' or 'master' server with all backends</term>
5625
6776
<listitem>
5626
6777
<para>
5627
Only the Generic SQL and BIND backends have the ability to act as master or slave.
6778
Only the Generic SQL, OpenDBX and BIND backends have the ability to act as master or slave.
5628
6779
</para>
5629
6780
</listitem>
5630
6781
</varlistentry>
5845
6996
</chapter>
5846
6997
<chapter id="built-in-recursor"><title>PowerDNS resolver/recursing nameserver</title>
5847
6998
<para>
5848
As of 2.9.4, a small recursor comes with PowerDNS. The algorithm is influenced by the works of Dan J. Bernstein although
5849
all mistakes are ours. Here are the current faults, so nobody can accuse us of false advertising:
5850
<itemizedlist>
5851
<listitem><para>
5852
Only compiles on Linux, FreeBSD 5.x, Windows and possibly Solaris. FreeBSD 4.x decided not to support the
5853
POSIX get/set/swapcontext functions. Bug your favorite FreeBSD kernel or libc maintainer for a fix,
5854
or ask him to port MTasker (see below) to your operating system. It may work on recent 4.x systems,
5855
let us know!
5856
</para></listitem>
5857
<listitem><para>
5858
May have big problems with truncated packets (solved in 2.9.18)
5859
</para></listitem>
5860
</itemizedlist>
5861
</para>
5862
<para>
5863
To compile, add <command>--enable-recursor</command> to configure and the file <filename>pdns_recursor</filename> will be
5864
compiled. To run on a different port, use <command>./syncres --local-port=53</command>.
5865
To bind to another address, use the <command>local-address</command> setting.
5866
</para>
5867
5868
<para>
5869
Good points:
6999
The PowerDNS recursor is part of the source tarball of the main PowerDNS distribution, but it is released separately. Starting from
7000
the version 3.0 pre-releases, there are zero known bugs or issues with the recursor. It is known to power the resolving needs of over 2 million
7001
internet connections.
7002
</para>
7003
<para>
7004
The documentation below is only for the 3.0 series, users of older versions are urged to upgrade!
7005
</para>
7006
<para>
7007
Notable features:
5870
7008
<itemizedlist>
5871
7009
<listitem><para>
5872
7010
Uses MTasker (<ulink url="http://ds9a.nl/mtasker">homepage</ulink>)
5873
7011
</para></listitem>
5874
7012
<listitem><para>
5875
Can handle thousands of concurrent questions
5876
</para></listitem>
5877
<listitem><para>
5878
Appears to be very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers.
7013
Can handle thousands of concurrent questions. A dual Xeon 3GHz has been measured functioning very well at 9000 real life replayed
7014
packets per second, with 40% cpu idle. More testing equipment is needed to max out the recursor.
7015
</para></listitem>
7016
<listitem><para>
7017
Powered by a highly modern DNS packet parser that should be resistant against many forms of buffer overflows.
7018
</para></listitem>
7019
<listitem><para>
7020
Best spoofing protection that we know about, involving both source port randomisation and spoofing detection.
7021
</para></listitem>
7022
<listitem><para>
7023
Uses 'connected' UDP sockets which allow the recursor to react quickly to unreachable hosts or hosts for which
7024
the server is running, but the nameserver is down. This makes the recursor faster to respond in case of misconfigured domains,
7025
which are sadly very frequent.
7026
</para></listitem>
7027
<listitem><para>
7028
Special support for FreeBSD, Linux and Solaris stateful multiplexing (kqueue, epoll, completion ports).
7029
</para></listitem>
7030
<listitem><para>
7031
Very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers.
5879
7032
</para></listitem>
5880
7033
<listitem><para>
5881
7034
Code is written linearly, sequentially, which means that there are no problems with 'query restart' or anything.
5884
7037
Relies heavily on Standard C++ Library infrastructure, which makes for little code (406 core lines).
5885
7038
</para></listitem>
5886
7039
<listitem><para>
5887
Is very verbose in showing how recursion actually works.
7040
Is very verbose in showing how recursion actually works, when enabled to do so with --verbose.
5888
7041
</para></listitem>
5889
7042
<listitem><para>
5890
7043
The algorithm is simple and quite nifty.
5891
7044
</para></listitem>
5892
7045
</itemizedlist>
5893
7046
</para>
5894
<sect1><title>pdns_recursor settings</title>
7047
<para>
7048
The PowerDNS recursor is controlled and queried using the <filename>rec_control</filename> tool.
7049
<sect1 id="recursor-settings"><title>pdns_recursor settings</title>
5895
7050
<para>
5896
7051
At startup, the recursing nameserver reads the file <filename>recursor.conf</filename> from the configuration directory,
5897
often <filename>/etc/powerdns</filename> or <filename>/usr/local/etc</filename>.
7052
often <filename>/etc/powerdns</filename> or <filename>/usr/local/etc</filename>. Each setting below can appear on the command line,
7053
prefixed by '--', or in the configuration file. The command line overrides the configuration file.
7054
</para>
7055
<para>
7056
A switch can be set to on simply by passing it, like '--daemon', and turned off explicitly by '--daemon=off' or '--daemon=no'.
5898
7057
</para>
5899
7058
<para>
5900
7059
The following settings can be configured:
5910
7069
</listitem>
5911
7070
</varlistentry>
5912
7071
<varlistentry>
7072
<term>allow-from</term>
7073
<listitem>
7074
<para>
7075
Comma separated netmasks (both IPv4 and IPv6) that are allowed to use the server. The default allows access only from RFC 1918
7076
private IP addresses, like 10.0.0.0/8. Due to the agressive nature of the internet these days, it is highly recommended
7077
to not open up the recursor for the entire internet. Questions from IP addresses not listed here are ignored and do
7078
not get an answer.
7079
</para>
7080
</listitem>
7081
</varlistentry>
7082
<varlistentry>
7083
<term>auth-can-lower-ttl</term>
7084
<listitem>
7085
<para>
7086
Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone. This is called a
7087
'delegation inconsistency'. To follow RFC 2181 paragraphs 5.2 and 5.4 to the letter, enable this feature.
7088
This will mean a slight deterioration of performance, and it will not solve any problems, but does make
7089
the recursor more standards compliant. Not recommended unless you have to tick an 'RFC 2181 compliant' box. Off by default.
7090
</para>
7091
</listitem>
7092
</varlistentry>
7093
<varlistentry>
7094
<term>auth-zones</term>
7095
<listitem>
7096
<para>
7097
Comma separated list of 'zonename=filename' pairs. Zones read from these files are served authoritatively. Example:
7098
<command>auth-zones= ds9a.nl=/var/zones/ds9a.nl, powerdns.com=/var/zones/powerdns.com</command>. Available since 3.1.
7099
</para>
7100
</listitem>
7101
</varlistentry>
7102
<varlistentry><term>chroot</term>
7103
<listitem><para>
7104
If set, chroot to this directory for more security. See <xref linkend="security">.
7105
</para></listitem></varlistentry>
7106
<varlistentry>
5913
7107
<term>client-tcp-timeout</term>
5914
7108
<listitem>
5915
7109
<para>
5916
Time to wait for data from TCP clients. Defaults to 2 seconds. Available since 2.9.18.
7110
Time to wait for data from TCP clients. Defaults to 2 seconds.
5917
7111
</para>
5918
7112
</listitem>
5919
7113
</varlistentry>
5937
7131
<term>delegation-only</term>
5938
7132
<listitem>
5939
7133
<para>
5940
A Verisign special, see <xref linkend="verisign">.
5941
</para>
5942
</listitem>
5943
</varlistentry>
5944
<varlistentry>
5945
<term>hints-file</term>
5946
<listitem>
5947
<para>
5948
If set, the root-hints are read form this file. If unset, default root hints are used. Available since 2.9.19.
7134
A Verisign special.
7135
</para>
7136
</listitem>
7137
</varlistentry>
7138
<varlistentry>
7139
<term>dont-query</term>
7140
<listitem>
7141
<para>
7142
The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1. This can have odd effects,
7143
depending on your network, and may even be a security risk. Therefore, since version 3.1.5, the PowerDNS recursor by default does not query
7144
private space IP addresses. This setting can be used to expand or reduce the limitations.
7145
</para>
7146
</listitem>
7147
</varlistentry>
7148
<varlistentry>
7149
<term>export-etc-hosts</term>
7150
<listitem>
7151
<para>
7152
If set, this flag will export the host names and IP addresses mentioned in <filename>/etc/hosts</filename>. Available since 3.1.
7153
</para>
7154
</listitem>
7155
</varlistentry>
7156
7157
<varlistentry>
7158
<term>fork</term>
7159
<listitem>
7160
<para>
7161
If running on an SMP system with enough memory, this feature forks PowerDNS so it benefits from two processors. Experimental. Renames
7162
controlsockets, so care is needed to connect to the right one using <command>rec_control</command>, using <command>--socket-pid</command>.
7163
</para>
7164
</listitem>
7165
</varlistentry>
7166
<varlistentry>
7167
<term>forward-zones</term>
7168
<listitem>
7169
<para>
7170
Comma separated list of 'zonename=IP' pairs. Queries for zones listed here will be forwarded to the IP address listed.
7171
<command>forward-zones= ds9a.nl=213.244.168.210, powerdns.com=127.0.0.1</command>. Available since 3.1.
7172
</para>
7173
</listitem>
7174
</varlistentry>
7175
<varlistentry>
7176
<term>forward-zones-file</term>
7177
<listitem>
7178
<para>
7179
Same as <command>forward-zones</command>, parsed from a file. Only 1 zone is allowed per line, specified as follows:
7180
<command>ds9a.nl=213.244.168.210</command>. Available since 3.1.5.
7181
</para>
7182
</listitem>
7183
</varlistentry>
7184
7185
<varlistentry>
7186
<term>hint-file</term>
7187
<listitem>
7188
<para>
7189
If set, the root-hints are read from this file. If unset, default root hints are used. Available since 2.9.19.
5949
7190
</para>
5950
7191
</listitem>
5951
7192
</varlistentry>
5954
7195
<term>local-address</term>
5955
7196
<listitem>
5956
7197
<para>
5957
Local IP address (singular) to bind to. Defaults to all addresses.
7198
Local IPv4 or IPv6 addresses to bind to, comma separated. Defaults to only loopback. Addresses can also contain port numbers,
7199
for IPv4 specify like this: <command>1.2.3.4:5300</command>, for IPv6: <command>[::1]:5300</command>. Port specifications are available since
7200
3.1.2.
5958
7201
</para>
5959
7202
</listitem>
5960
7203
</varlistentry>
5967
7210
</para>
5968
7211
</listitem>
5969
7212
</varlistentry>
7213
7214
<varlistentry>
7215
<term>log-common-errors</term>
7216
<listitem>
7217
<para>
7218
Some DNS errors occur rather frequently and are no cause for alarm. Logging these is on by default.
7219
</para>
7220
</listitem>
7221
</varlistentry>
7222
<varlistentry>
7223
<term>logging-facility</term>
7224
<listitem>
7225
<para>
7226
If set to a digit, logging is performed under this LOCAL facility. See <xref linkend="syslog"/>. Available from 3.1.3 and onwards. Do not pass names like 'local0'!
7227
</para>
7228
</listitem>
7229
</varlistentry>
7230
7231
7232
<varlistentry>
7233
<term>max-cache-entries</term>
7234
<listitem>
7235
<para>
7236
Maximum number of cache entries. 1 million will generally suffice for most installations.
7237
</para>
7238
</listitem>
7239
</varlistentry>
7240
<varlistentry>
7241
<term>max-negative-ttl</term>
7242
<listitem>
7243
<para>
7244
A query for which there is authoritatively no answer is cached to quickly deny a record's existence later on, without
7245
putting a heavy load on the remote server. In practice, caches can become saturated with hundreds of thousands of hosts
7246
which are tried only once. This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative
7247
entries are cached.
7248
</para>
7249
</listitem>
7250
</varlistentry>
5970
7251
<varlistentry>
5971
7252
<term>max-tcp-clients</term>
5972
7253
<listitem>
5976
7257
</listitem>
5977
7258
</varlistentry>
5978
7259
<varlistentry>
7260
<term>max-tcp-per-client</term>
7261
<listitem>
7262
<para>
7263
Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). Defaults to 0, which means unlimited.
7264
</para>
7265
</listitem>
7266
</varlistentry>
7267
<varlistentry>
5979
7268
<term>query-local-address</term>
5980
7269
<listitem>
5981
7270
<para>
5984
7273
</listitem>
5985
7274
</varlistentry>
5986
7275
<varlistentry>
7276
<term>query-local-address6</term>
7277
<listitem>
7278
<para>
7279
Send out local IPv6 queries from this address. Disabled by default, which also disables
7280
outgoing IPv6 support. A useful setting is <command>::0</command>.
7281
</para>
7282
</listitem>
7283
</varlistentry>
7284
7285
<varlistentry>
5987
7286
<term>quiet</term>
5988
7287
<listitem>
5989
7288
<para>
5990
Don't log queries.
7289
Don't log queries. On by default.
7290
</para>
7291
</listitem>
7292
</varlistentry>
7293
<varlistentry>
7294
<term>remotes-ringbuffer-entries</term>
7295
<listitem>
7296
<para>
7297
Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. Can be read out using
7298
<command>rec_control top-remotes</command>. Defaults to 0.
7299
</para>
7300
</listitem>
7301
</varlistentry>
7302
<varlistentry>
7303
<term>serve-rfc1918</term>
7304
<listitem>
7305
<para>
7306
On by default, this makes the server authoritatively aware of: <filename>10.in-addr.arpa</filename>,
7307
<filename>168.192.in-addr.arpa</filename>, <filename>16-31.172.in-addr.arpa</filename>, which saves
7308
load on the AS112 servers. Individual parts of these zones can still be loaded or forwarded.
7309
</para>
7310
</listitem>
7311
</varlistentry>
7312
<varlistentry>
7313
<term>server-id</term>
7314
<listitem>
7315
<para>
7316
The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. Use this setting to override
7317
the answer it gives.
7318
</para>
7319
</listitem>
7320
</varlistentry>
7321
<varlistentry>
7322
<term>setgid</term>
7323
<term>setuid</term>
7324
<listitem>
7325
<para>
7326
PowerDNS can change its user and group id after binding to its socket. Can be used for better security.
7327
</para>
7328
</listitem>
7329
</varlistentry>
7330
<varlistentry>
7331
<term>socket-dir</term>
7332
<listitem>
7333
<para>
7334
Where to store the control socket. This option also works with the controller, <command>rec_control</command>.
7335
</para>
7336
</listitem>
7337
</varlistentry>
7338
<varlistentry>
7339
<term>spoof-nearmiss-max</term>
7340
<listitem>
7341
<para>
7342
If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. Defaults to 20.
5991
7343
</para>
5992
7344
</listitem>
5993
7345
</varlistentry>
5999
7351
</para>
6000
7352
</listitem>
6001
7353
</varlistentry>
7354
<varlistentry>
7355
<term>version</term>
7356
<listitem>
7357
<para>
7358
Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. Available since 3.1.5.
7359
</para>
7360
</listitem>
7361
</varlistentry>
7362
<varlistentry>
7363
<term>version-string</term>
7364
<listitem>
7365
<para>
7366
By default, PowerDNS replies to the 'version.bind' query with its version number. Security concious users may wish to override
7367
the reply PowerDNS issues.
7368
</para>
7369
</listitem>
7370
</varlistentry>
6002
7371
</variablelist>
6003
7372
<para>
6004
<sect2 id="verisign"><title>Verisign weirdness</title>
6005
<para>
6006
Verisign, the current operator of the COM and NET zones, decided to add a wildcard record so as to draw all queries for non-existing
6007
domains to their own page, which lists domains you might want to visist instead.
6008
</para>
6009
<para>
6010
To reinstate old behaviour, add <command>delegation-only=com,net</command> to your recursor configuration.
6011
</para>
6012
<para>
6013
What this does is reject all authoritative answers from the COM and NET servers. ISC, the current maintainers of BIND, have
6014
implemented this feature first, PowerDNS has mostly copied their algorithm. Thanks!
6015
</para>
6016
<para>
6017
Verisign might decide to evade our tactic with wildcard NS records, by which time other measures will be needed to restore the
6018
old behaviour.
6019
</para>
6020
</sect2>
6021
7373
</sect1>
7374
<sect1 id="rec-control"><title>Controlling and querying the recursor</title>
7375
<para>
7376
To control and query the PowerDNS recursor, the tool <filename>rec_control</filename> is provided. This program
7377
talks to the recursor over the 'controlsocket', often stored in <filename>/var/run</filename>.
7378
</para>
7379
<para>
7380
As a sample command, try:
7381
<screen>
7382
# rec_control ping
7383
pong
7384
</screen>
7385
</para>
7386
<para>
7387
When not running as root, <command>--socket-dir=/tmp</command> might be appropriate.
7388
</para>
7389
<para>
7390
All rec_control commands are documented below:
7391
<variablelist>
7392
<varlistentry>
7393
<term>dump-cache filename</term>
7394
<listitem>
7395
<para>
7396
Dumps the entire cache to the filename mentioned. This file should not exist already, PowerDNS
7397
will refuse to overwrite it. While dumping, the recursor will not answer questions.
7398
</para>
7399
</listitem>
7400
</varlistentry>
7401
<varlistentry>
7402
<term>get statistic</term>
7403
<listitem>
7404
<para>
7405
Retrieve a statistic. For items that can be queried, see below.
7406
</para>
7407
</listitem>
7408
</varlistentry>
7409
<varlistentry>
7410
<term>ping</term>
7411
<listitem>
7412
<para>
7413
Check if server is alive.
7414
</para>
7415
</listitem>
7416
</varlistentry>
7417
<varlistentry>
7418
<term>quit</term>
7419
<listitem>
7420
<para>
7421
Request shutdown of the recursor.
7422
</para>
7423
</listitem>
7424
</varlistentry>
7425
<varlistentry>
7426
<term>reload-zones</term>
7427
<listitem>
7428
<para>
7429
Reload data about all authoritative and forward zones. The configuration file is also scanned
7430
to see if the <command>auth-domain</command>, <command>forward-domain</command> and <command>export-etc-hosts</command>
7431
statements have changed, and if so, these changes are incorporated.
7432
</para>
7433
</listitem>
7434
</varlistentry>
7435
<varlistentry>
7436
<term>top-remotes</term>
7437
<listitem>
7438
<para>
7439
Shows the top-20 most active remote hosts. Statistics are over the last 'remotes-ringbuffer-entries' queries, which
7440
defaults to 0.
7441
</para>
7442
</listitem>
7443
</varlistentry>
7444
<varlistentry>
7445
<term>wipe-cache domain0. [domain1. domain2.]</term>
7446
<listitem>
7447
<para>
7448
Wipe entries from the cache. This is useful if, for example, an important server has a new IP address, but the TTL has not
7449
yet expired. Multiple domain names can be passed. For versions before 3.1, you must terminate a domain with a .! So to wipe powerdns.org,
7450
issue 'rec_control wipe-cache powerdns.org.'. For later versions, the dot is optional.
7451
</para>
7452
<para>
7453
Note that deletion is exact, wiping 'com.' will leave 'www.powerdns.com.' untouched!
7454
</para>
7455
<para>
7456
<warning>
7457
<para>
7458
In PowerDNS versions 3.0.0 and 3.0.1 this command is slightly buggy and might cause your nameserver to crash if the first
7459
query after wiping the cache is for the domain you just wiped.
7460
</para>
7461
</warning>
7462
<warning>
7463
<para>
7464
Don't just wipe 'www.somedomain.com', its NS records or CNAME target may still be undesired, so wipe 'somedomain.com' as well.
7465
</para>
7466
</warning>
7467
</para>
7468
</listitem>
7469
</varlistentry>
7470
</variablelist>
7471
</para>
7472
<para>
7473
The command 'get' can query a large number of statistics, which are detailed in <xref linkend="recursor-stats">.
6022
7474
7475
</para>
7476
<para>
7477
More details on what 'throttled' queries and the like are can be found below in <xref linkend="recursor-details">.
7478
</para>
6023
7479
</sect1>
6024
<sect1><title>Details</title>
6025
<para>
6026
PowerDNS implements a very simple but effective nameserver. Care has been taken not to overload remote servers in case
6027
of overly active clients.
6028
</para>
6029
<para>
6030
This is implemented using the 'throttle'. This accounts all recent traffic and prevents queries that have been sent out
6031
recently from going out again.
6032
</para>
6033
<para>
6034
There are three levels of throttling.
7480
<sect1 id="recursor-performance"><title>PowerDNS Recursor performance</title>
7481
<para>
7482
To get the best out of the PowerDNS recursor, which is important if you are doing thousands of queries per second, please
7483
consider the following.
6035
7484
<itemizedlist>
6036
7485
<listitem>
6037
7486
<para>
6038
If a remote server indicates that it is lame for a zone, the exact question won't
6039
be repeated in the next 60 seconds.
6040
</para>
6041
</listitem>
6042
<listitem>
6043
<para>
6044
After 4 ServFail responses in 60 seconds, the query gets throttled too.
6045
</para>
6046
</listitem>
6047
<listitem>
6048
<para>
6049
5 timeouts in 20 seconds also lead to query suppression.
7487
Limit the size of the cache to a sensible value. Cache hit rate does not improve meaningfully beyond 4 million <command>max-cache-entries</command>,
7488
reducing the memory footprint reduces CPU cache misses.
7489
</para>
7490
</listitem>
7491
<listitem>
7492
<para>
7493
Compile using g++ 4.1 or later. This compiler really does a good job on PowerDNS, much better than 3.4 or 4.0.
7494
</para>
7495
</listitem>
7496
<listitem>
7497
<para>
7498
Consider performing a 'profiled build' as described in the README. This is good for a 20% performance boost in some cases.
7499
</para>
7500
</listitem>
7501
<listitem>
7502
<para>
7503
When running with >3000 queries per second, and running Linux versions prior to 2.6.17 on some motherboards, your computer may
7504
spend an inordinate amount of time working around an ACPI bug for each call to gettimeofday. This is solved by rebooting with 'clock=tsc'
7505
or upgrading to a 2.6.17 kernel.
7506
</para>
7507
<para>
7508
The above is relevant if dmesg shows <command>Using pmtmr for high-res timesource</command>
7509
</para>
7510
</listitem>
7511
<listitem>
7512
<para>
7513
A busy server may need hundreds of file descriptors on startup, and deals with spikes better if it has that many available
7514
later on. Linux by default restricts processes to 1024 file descriptors, which should suffice most of the time, but Solaris
7515
has a default limit of 256. This can be raised using the ulimit command. FreeBSD has a default limit that is high enough for even
7516
very heavy duty use.
7517
</para>
7518
</listitem>
7519
<listitem>
7520
<para>
7521
If you need it, try <command>--fork</command>, this will fork the daemon into two halves, allowing it to benefit from a second CPU.
7522
This feature almost doubles performance, but is a bit of a hack.
6050
7523
</para>
6051
7524
</listitem>
6052
7525
</itemizedlist>
6053
</para>
6054
</sect1>
6055
<sect1><title>Statistics</title>
7526
Following the instructions above, you should be able to attain very high query rates.
7527
</para>
7528
</sect1>
7529
<sect1 id="recursor-details"><title>Details</title>
7530
<sect2 id="anti-spoofing"><title>Anti-spoofing</title>
7531
<para>
7532
The PowerDNS recursor 3.0 uses a fresh UDP source port for each outgoing query, making spoofing around 64000 times harder. This
7533
raises the bar from 'easily doable given some time' to 'very hard'. Under some circimstances, 'some time' has been measured at 2 seconds.
7534
This technique was first used by <filename>dnscache</filename> by Dan J. Bernstein.
7535
</para>
7536
<para>
7537
In addition, PowerDNS detects when it is being sent too many unexpected answers, and mistrusts a proper answer if found within
7538
a clutch of unexpected ones.
7539
</para>
7540
<para>
7541
This behaviour can be tuned using the <command>spoof-nearmiss-max</command>.
7542
</para>
7543
</sect2>
7544
<sect2><title>Throttling</title>
7545
<para>
7546
PowerDNS implements a very simple but effective nameserver. Care has been taken not to overload remote servers in case
7547
of overly active clients.
7548
</para>
7549
<para>
7550
This is implemented using the 'throttle'. This accounts all recent traffic and prevents queries that have been sent out
7551
recently from going out again.
7552
</para>
7553
<para>
7554
There are three levels of throttling.
7555
<itemizedlist>
7556
<listitem>
7557
<para>
7558
If a remote server indicates that it is lame for a zone, the exact question won't
7559
be repeated in the next 60 seconds.
7560
</para>
7561
</listitem>
7562
<listitem>
7563
<para>
7564
After 4 ServFail responses in 60 seconds, the query gets throttled too.
7565
</para>
7566
</listitem>
7567
<listitem>
7568
<para>
7569
5 timeouts in 20 seconds also lead to query suppression.
7570
</para>
7571
</listitem>
7572
</itemizedlist>
7573
</para>
7574
</sect2>
7575
7576
</sect1>
7577
<sect1 id="recursor-stats"><title>Statistics</title>
7578
<para>
7579
The <command>rec_control get</command> command can be used to query the following keys, either single keys or multiple keys
7580
at once:
7581
<screen>
7582
all-outqueries counts the number of outgoing UDP queries since starting
7583
answers0-1 counts the number of queries answered within 1 milisecond
7584
answers100-1000 counts the number of queries answered within 1 second
7585
answers10-100 counts the number of queries answered within 100 miliseconds
7586
answers1-10 counts the number of queries answered within 10 miliseconds
7587
answers-slow counts the number of queries answered after 1 second
7588
cache-entries shows the number of entries in the cache
7589
cache-hits counts the number of cache hits since starting
7590
cache-misses counts the number of cache misses since starting
7591
chain-resends number of queries chained to existing outstanding query
7592
client-parse-errors counts number of client packets that could not be parsed
7593
concurrent-queries shows the number of MThreads currently running
7594
dlg-only-drops number of records dropped because of delegation only setting
7595
negcache-entries shows the number of entries in the Negative answer cache
7596
noerror-answers counts the number of times it answered NOERROR since starting
7597
nsspeeds-entries shows the number of entries in the NS speeds map
7598
nsset-invalidations number of times an nsset was dropped because it no longer worked
7599
nxdomain-answers counts the number of times it answered NXDOMAIN since starting
7600
outgoing-timeouts counts the number of timeouts on outgoing UDP queries since starting
7601
qa-latency shows the current latency average
7602
questions counts all End-user initiated queries with the RD bit set
7603
resource-limits counts number of queries that could not be performed because of resource limits
7604
server-parse-errors counts number of server replied packets that could not be parsed
7605
servfail-answers counts the number of times it answered SERVFAIL since starting
7606
spoof-prevents number of times PowerDNS considered itself spoofed, and dropped the data
7607
sys-msec number of CPU milliseconds spent in 'system' mode
7608
tcp-client-overflow number of times an IP address was denied TCP access because it already had too many connections
7609
tcp-outqueries counts the number of outgoing TCP queries since starting
7610
tcp-questions counts all incoming TCP queries (since starting)
7611
throttled-out counts the number of throttled outgoing UDP queries since starting
7612
throttle-entries shows the number of entries in the throttle map
7613
unauthorized-tcp number of TCP questions denied because of allow-from restrictions
7614
unauthorized-udp number of UDP questions denied because of allow-from restrictions
7615
unexpected-packets number of answers from remote servers that were unexpected (might point to spoofing)
7616
uptime number of seconds process has been running (since 3.1.5)
7617
user-msec number of CPU milliseconds spent in 'user' mode
7618
</screen>
7619
In the <filename>rrd/</filename> subdirectory a number of rrdtool scripts is provided to make nice
7620
graphs of all these numbers.
7621
</para>
6056
7622
<para>
6057
7623
Every half our or so, the recursor outputs a line with statistics. More infrastructure is planned so as to allow
6058
7624
for Cricket or MRTG graphs. To force the output of statistics, send the process a SIGUSR1. A line of statistics looks
6072
7638
Finally, 12% of queries were not performed because identical queries had gone out previously, saving load servers worldwide.
6073
7639
</para>
6074
7640
</sect1>
7641
<sect1 id="recursor-design-and-engineering">
7642
<title>Design and Engineering of the PowerDNS Recursor</title>
7643
<para>
7644
<warning>
7645
<para>
7646
This section is aimed at programmers wanting to contibute to the recursor, or to help fix bugs. It is not required
7647
reading for a PowerDNS operator, although it might prove interesting.
7648
</para>
7649
</warning>
7650
</para>
7651
<para>The PowerDNS Recursor consists of very little code, the core DNS logic is less than a thousand lines.</para>
7652
7653
<para>This smallness is achieved through the use of some fine infrastructure: MTasker, MOADNSParser, MPlexer and the C++ Standard Library/Boost. This page will explain the conceptual relation between these components, and the route of a packet through the program.</para>
7654
7655
<sect2>
7656
<title>The PowerDNS Recursor</title>
7657
<para>The Recursor started out as a tiny project, mostly a technology demonstration. These days it consists of the core plus 9000 lines of features. This combined with a need for very high performance has made the recursor code less accessible than it was. The page you are reading hopes to rectify this situation.</para>
7658
7659
</sect2>
7660
<sect2>
7661
<title>Synchronous code using MTasker</title>
7662
<para>The original name of the program was <command>syncres</command>, which is still reflected in the filename <literal>syncres.cc</literal>, and the class SyncRes. This means that PowerDNS is written naively, with one thread of execution per query, synchronously waiting for packets, Normally this would lead to very bad performance (unless running on a computer with very fast threading, like possibly the Sun CoolThreads family), so PowerDNS employs <ulink url="http://ds9a.nl/mtasker">MTasker</ulink> for very fast userspace threading.</para>
7663
7664
<para>MTasker, which was developed separately from PowerDNS, does not provide a full multithreading system but restricts itself to those features a nameserver needs. It offers cooperative multitasking, which means there is no forced preemption of threads. This in turn means that no two <command>MThreads</command> ever really run at the same time.</para>
7665
7666
<para>This is both good and bad, but mostly good. It means PowerDNS does not have to think about locking. No two threads will ever be talking to the DNS cache at the same time, for example.</para>
7667
7668
<para>It also means that the recursor could block if any operation takes too long.</para>
7669
7670
<para>The core interaction with MTasker are the waitEvent() and sendEvent() functions. These pass around PacketID objects. Everything PowerDNS needs to wait for is described by a PacketID event, so the name is a bit misleading. Waiting for a TCP socket to have data available is also passed via a PacketID, for example.</para>
7671
7672
<para>The version of MTasker in PowerDNS is newer than that described at the MTasker site, with a vital difference being that thet waitEvent() structure passes along a copy of the exact PacketID sendEvent() transmitted. Furthermore, threads can trawl through the list of events being waited for and modify the respective PacketIDs. This is used for example with <command>near miss</command> packets: packets that appear to answer questions we asked, but differ in the DNS id. On seeing such a packet, the recursor trawls through all PacketIDs and if it finds any nearmisses, it updates the PacketID::nearMisses counter. The actual PacketID thus lives inside MTasker while any thread is waiting for it.</para>
7673
7674
</sect2>
7675
<sect2>
7676
<title>MPlexer</title>
7677
<para>The Recursor uses a separate socket per outgoing query. This has the important benefit of making spoofing 64000 times harder, and additionally means that ICMP errors are reported back to the program. In measurements this appears to happen to one in ten queries, which would otherwise take a two-second timeout before PowerDNS moves on to another nameserver.</para>
7678
7679
<para>However, this means that the program routinely needs to wait on hundreds or even thousands of sockets. Different operating systems offer various ways to monitor the state of sockets or more generally, filedescriptors. To abstract out the differing strategies (<function>select</function>, <function>epoll</function>, <function>kqueue</function>, <function>completion ports</function>), PowerDNS contains <command>MPlexer</command> classes, all of which descend from the FDMultiplexer class.</para>
7680
7681
<para>This class is very simple and offers only five important methods: addReadFD(), addWriteFD(), removeReadFD(), removeWriteFD() and run.</para>
7682
7683
<para>The arguments to the <command>add</command> functions consist of an fd, a callback, and a boost::any variable that is passed as a reference to the callback.</para>
7684
7685
<para>This might remind you of the MTasker above, and it is indeed the same trick: state is stored within the MPlexer. As long as a filedescriptor remains within either the Read or Write active list, its state will remain stored.</para>
7686
7687
<para>On arrival of a packet (or more generally, when an FD becomes readable or writable, which for example might mean a new TCP connection), the callback is called with the aforementioned reference to its parameter.</para>
7688
7689
<para>The callback is free to call removeReadFD() or removeWriteFD() to remove itself from the active list.</para>
7690
7691
<para>PowerDNS defines such callbacks as newUDPQuestion(), newTCPConnection(), handleRunningTCPConnection().</para>
7692
7693
<para>Finally, the run() method needs to be called whenever the program is ready for new data. This happens in the main loop in pdns_recursor.cc. This loop is what MTasker refers to as <command>the kernel</command>. In this loop, any packets or other MPlexer events get translated either into new MThreads within MTasker, or into calls to sendEvent(), which in turn wakes up other MThreads.</para>
7694
7695
</sect2>
7696
<sect2>
7697
<title>MOADNSParser</title>
7698
<para>Yes, this does stand for <command>the Mother of All DNS Parsers</command>. And even that name does not do it justice! The MOADNSParser is the third attempt I've made at writing DNS packet parser and after two miserable failures, I think I've finally gotten it right.</para>
7699
7700
<para>Writing and parsing DNS packets, and the DNS records it contains, consists of four things:
7701
<orderedlist>
7702
<listitem>
7703
<para>
7704
Parsing a DNS record (from packet) into memory
7705
</para>
7706
</listitem>
7707
<listitem>
7708
<para>
7709
Generating a DNS record from memory (to packet)
7710
</para>
7711
</listitem>
7712
<listitem>
7713
<para>
7714
Writing out memory to user-readable zone format
7715
</para>
7716
</listitem>
7717
<listitem>
7718
<para>
7719
Reading said zone format into memory
7720
</para>
7721
</listitem>
7722
</orderedlist>
7723
</para>
7724
7725
<para>This gets tedious very quickly, as one needs to implement all four operations for each new record type, and there are dozens of them.</para>
7726
7727
<para>While writing the MOADNSParser, it was discovered there is a remarkable symmetry between these four transitions. DNS Records are nearly always laid out in the same order in memory as in their zone format representation. And reading is nothing but inverse writing.</para>
7728
7729
<para>So, the MOADNSParser is built around the notion of a <command>Conversion</command>, and we write all Conversion types once. So we have a Conversion from IP address in memory to an IP address in a DNS packet, and vice versa. And we have a Conversion from an IP address in zone format to memory, and vice versa.</para>
7730
7731
<para>This in turn means that the entire implementation of the ARecordContent is as follows (wait for it!)</para>
7732
7733
<literallayout class="monospaced">conv.xfrIP(d_ip);</literallayout>
7734
<para>Through the use of the magic called <literal>c++ Templates</literal>, this one line does everything needed to perform the four operations mentioned above.</para>
7735
7736
<para>At one point, I got really obsessed with PowerDNS memory use. So, how do we store DNS data in the PowerDNS recorsor? I mentioned <command>memory</command> above a lot - this means we could just store the DNSRecordContent objects. However, this would be wasteful.</para>
7737
7738
<para>For example, storing the following:</para>
7739
7740
<literallayout class="monospaced">www.ds9a.nl 3600 IN CNAME outpost.ds9a.nl.</literallayout>
7741
<para>Would duplicate a lot of data. So, what is actually stored is a partial DNS packet. To store the CNAMEDNSRecordContent that corresponds to the above, we generate a DNS packet that has <command>www.ds9a.nl IN CNAME</command> as its question. Then we add <command>3600 IN CNAME outpost.ds9a.nl</command>. as its answer. Then we chop off the question part, and store the rest in the <command>www.ds9a.nl IN CNAME</command> key in our cache.</para>
7742
7743
<para>When we need to retrieve <command>www.ds9a.nl IN CNAME</command>, the inverse happens. We find the proper partial packet, prefix it with a question for <command>www.ds9a.nl IN CNAME</command>, and expand the resulting packet into the answer <command>3600 IN CNAME outpost.ds9a.nl.</command>.</para>
7744
7745
<para>Why do we go through all these motions? Because of DNS compression, which allows us to omit the whole <command>.ds9a.nl.</command> part, saving us 9 bytes. This is amplified when storing multiple MX records which all look more or less alike. This optimization is not performed yet though.</para>
7746
7747
<para>Even without compression, it makes sense as all records are automatically stored very compactly.</para>
7748
7749
<para>The PowerDNS recursor only parses a number of <command>well known record types</command> and passes all other information across verbatim - it doesn't have to know about the content it is serving.</para>
7750
7751
</sect2>
7752
<sect2>
7753
<title>The C++ Standard Library / Boost</title>
7754
<para>C++ is a powerful language. Perhaps a bit too powerful at times, you can turn a program into a real freakshow if you so desire.</para>
7755
7756
<para>PowerDNS generally tries not to go overboard in this respect, but we do build upon a very advanced part of the <ulink url="http://www.boost.org">Boost</ulink> C++ library:
7757
<ulink url="http://boost.org/libs/multi_index/doc/index.html">boost::multi index container</ulink>.</para>
7758
7759
<para>This container provides the equivalent of SQL indexes on multiple keys. It also implements compound keys, which PowerDNS uses as well.</para>
7760
7761
<para>The main DNS cache is implemented as a multi index container object, with a compound key on the name and type of a record. Furthermore, the cache is sequenced, each time a record is accessed it is moved to the end of the list. When cleanup is performed, we start at the beginning. New records also get inserted at the end. For DNS correctness, the sort order of the cache is case insensitive.</para>
7762
7763
<para>The multi index container appears in other parts of PowerDNS, and MTasker as well.</para>
7764
7765
</sect2>
7766
<sect2>
7767
<title>Actual DNS Algorithm</title>
7768
<para>The DNS rfcs do define the DNS algorithm, but you can't actually implement it exactly that way, it was written in 1987.</para>
7769
7770
<para>Also, like what happened to HTML, it is expected that even non-standards conforming domains work, and a sizeable fraction of them is misconfigured these days.</para>
7771
7772
<para>Everything begins with SyncRes::beginResolve(), which knows nothing about sockets, and needs to be passed a domain name, dns type and dns class which we are interested in. It returns a vector of DNSResourceRecord objects, ready for writing either into an answer packet, or for internal use.</para>
7773
7774
<para>After checking if the query is for any of the hardcoded domains (localhost, version.bind, id.server), the query is passed to SyncRes::doResolve, together with two vital parameters: the <literal>depth</literal> and <literal>beenthere</literal> set. As the word <command>recursor</command> implies, we will need to recurse for answers. The <command>depth</command> parameter documents how deep we've recursed already.</para>
7775
7776
<para>The <literal>beenthere</literal> set prevents loops. At each step, when a nameserver is queried, it is added to the <literal>beenthere</literal> set. No nameserver in the set will ever be queried again for the same question in the recursion process - we know for a fact it won't help us further. This prevents the process from getting stuck in loops.</para>
7777
7778
<para>SyncRes::doResolve first checks if there is a CNAME in cache, using SyncRes::doCNAMECacheCheck, for the domain name and type queried and if so, changes the query (which is passed by reference) to the domain the CNAME points to. This is the cause of many DNS problems, a CNAME record really means <command>start over with this query</command>.</para>
7779
7780
<para>This is followed by a call do SyncRes::doCacheCheck, which consults the cache for a straight answer to the question (as possibly rerouted by a CNAME). This function also consults the so called negative cache, but we won't go into that just yet.</para>
7781
7782
<para>If this function finds the correct answer, and the answer hasn't expired yet, it gets returned and we are (almost) done. This happens in 80 to 90% of all queries. Which is good, as what follows is a lot of work.</para>
7783
7784
<para>To recap:
7785
<orderedlist>
7786
<listitem>
7787
<para>
7788
beginResolve() - entry point, does checks for hardcoded domains
7789
</para>
7790
</listitem>
7791
<listitem>
7792
<para>
7793
doResolve() - start of recursion process, gets passed <literal>depth</literal> of 0 and empty <literal>beenthere</literal> set
7794
</para>
7795
</listitem>
7796
<listitem>
7797
<para>
7798
doCNAMECacheCheck() - check if there is a CNAME in cache which would reroute the query
7799
</para>
7800
</listitem>
7801
<listitem>
7802
<para>
7803
doCacheCheck() - see if cache contains straight answer to possibly rerouted query.
7804
</para>
7805
</listitem>
7806
</orderedlist>
7807
</para>
7808
<para>If the data we were queried for was in the cache, we are almost done. One final step, which might as well be optional as nobody benefits from it, is SyncRes::addCruft. This function does additional processing, which means that if the query was for the MX record of a domain, we also add the IP address of the mail exchanger.</para>
7809
7810
</sect2>
7811
<sect2>
7812
<title>The non-cached case</title>
7813
<para>This is where things get interesting, because we start out with a nearly empty cache and have to go out to the net to get answers to fill it.</para>
7814
7815
<para>The way DNS works, if you don't know the answer to a question, you find somebody who does. Initially you have no other place to go than the root servers. This is embodied in the SyncRes::getBestNSNamesFromCache method, which gets passed the domain we are interested in, as well as the <literal>depth</literal> and <literal>beenthere</literal> parameters mentioned earlier.</para>
7816
7817
<para>From now on, assume our query will be for <command><literal>www.powerdns.com.</literal></command>. SyncRes::getBestNSNamesFromCache will first check if there are NS records in cache for <literal><command>www.powerdns.com.</command></literal>, but there won't be. It then checks <literal>powerdns.com. NS</literal>, and while these records do exist on the internet, the recursor doesn't know about them yet. So, we go on to check the cache for <literal><command>com. NS</command></literal>, for which the same holds. Finally we end up checking for <literal><command>. NS</command></literal>, and these we do know about: they are the root servers and were loaded into PowerDNS on startup.</para>
7818
7819
<para>So, SyncRes::getBestNSNamesFromCache fills out a set with the <command>names</command> of nameservers it knows about for the <command><literal>.</literal></command> zone.</para>
7820
7821
<para>This set, together with the original query <command><literal>www.powerdns.com</literal></command> gets passed to SyncRes::doResolveAt. This function can't yet go to work immediately though, it only knows the names of nameservers it can try. This is like asking for directions and instead of hearing <command>take the third right</command> you are told <command>go to 123 Fifth Avenue, and take a right</command> - the answer doesn't help you further unless you know where 123 Fifth Avenue is.</para>
7822
7823
<para>SyncRes::doResolveAt first shuffles the nameservers both randomly and on performance order. If it knows a nameserver was fast in the past, it will get queried first. More about this later.</para>
7824
7825
<para>Ok, here is the part where things get a bit scary. How does SyncRes::doResolveAt find the IP address of a nameserver? Well, by calling SyncRes::getAs (<command>get A records</command>), which in turn calls.. SyncRes::doResolve. Hang on! That's where we came from! Massive potential for loops here. Well, it turns out that for any domain which can be resolved, this loop terminates. We do pass the <literal>beenthere</literal> set again, which makes sure we don't keep on asking the same questions to the same nameservers.</para>
7826
7827
<para>Ok, SyncRes::getAs will give us the IP addresses of the chosen root-server, because these IP addresses were loaded on startup. We then ask these IP addresses (nameservers can have several) for its best answer for <command><literal>www.powerdns.com.</literal></command>. This is done using the LWRes class and specifically LWRes::asyncresolve, which gets passed domain name, type and IP address. This function interacts with MTasker and MPlexer above in ways which needn't concern us now. When it returns, the LWRes object contains the best answers the queried server had for our domain, which in this case means it tells us about the nameservers of <literal>com.</literal>, and their IP addresses.</para>
7828
7829
<para>All the relevant answers it gives are stored in the cache (or actually, merged), after which SyncRes::doResolveAt (which we are still in) evaluates what to do now.</para>
7830
7831
<para>There are 6 options:
7832
<orderedlist>
7833
<listitem>
7834
<para>
7835
The final answer is in, we are done, return to SyncRes::doResolve and SyncRes::beginResolve
7836
</para>
7837
</listitem>
7838
<listitem>
7839
<para>
7840
The nameserver we queried tells us the domain we asked for authoritatively does not exist. In case of the root-servers, this happens when we query for <emphasis><literal>www.powerdns.kom.</literal></emphasis> for example, there is no <emphasis><literal>kom.</literal></emphasis>. Return to SyncRes::beginResolve, we are done.
7841
</para>
7842
</listitem>
7843
<listitem>
7844
<para>
7845
A lesser form - it tells us it is authoritative for the query we asked about, but there is no record matching our type. This happens when querying for the IPv6 address of a host which only has an IPv4 address. Return to SyncRes::beginResolve, we are done.
7846
</para>
7847
</listitem>
7848
<listitem>
7849
<para>
7850
The nameserver passed us a CNAME to another domain, and we need to reroute. Go to SyncRes::doResolve for the new domain.
7851
</para>
7852
</listitem>
7853
<listitem>
7854
<para>
7855
The namserver did not know about the domain, but does know who does, a <emphasis>referral</emphasis>. Stay within doResolveAt and loop to these new nameservers.
7856
</para>
7857
</listitem>
7858
<listitem>
7859
<para>
7860
The nameserver replied saying <emphasis>no idea</emphasis>. This is called a <emphasis>lame delegation</emphasis>. Stay within SyncRes::doResolveAt and try the other nameservers we have for this domain.
7861
</para>
7862
</listitem>
7863
</orderedlist>
7864
</para>
7865
<para>When not redirected using a CNAME, this function will loop until it has exhausted all nameservers and all their IP addresses. DNS is surprisingly resilient that there is often only a single non-broken nameserver left to answer queries, and we need to be prepared for that.</para>
7866
7867
<para>This is the whole DNS algorithm in PowerDNS, all in less than 700 lines of code. It contains a lot of tricky bits though, related to the cache.</para>
7868
7869
</sect2>
7870
<sect2>
7871
<title>Some of the things we glossed over</title>
7872
<para>Whenever a packet is sent to a remote nameserver, the response time is stored in the SyncRes::s_nsSpeeds map, using an exponentially weighted moving average. This EWMA averages out different response times, and also makes them decrease over time. This means that a nameserver that hasn't been queried recently gradually becomes <command>faster</command> in the eyes of PowerDNS, giving it a chance again.</para>
7873
7874
<para>A timeout is accounted as a 1s response time, which should take that server out of the running for a while.</para>
7875
7876
<para>Furthermore, queries are throttled. This means that each query to a nameserver that has failed is accounted in the <literal>s_throttle</literal> object. Before performing a new query, the query and the nameserver are looked up via shouldThrottle. If so, the query is assumed to have failed without even being performed. This saves a lot of network traffic and makes PowerDNS quick to respond to lame servers.</para>
7877
7878
<para>It also offers a modicum of protection against birthday attack powered spoofing attempts, as PowerDNS will not innundate a broken server with queries.</para>
7879
7880
<para>The negative query cache we mentioned earlier caches the cases 2 and 3 in the enumeration above. This data needs to be stored separately, as it represents <command>non-data</command>. Each negcache query entry is the name of the SOA record that was presented with the evidence of non-existance. This SOA record is then retrieved from the regular cache, but with the TTL that originally came with the NXDOMAIN (case 2) or NXRRSET (case 3).</para>
7881
7882
</sect2>
7883
<sect2>
7884
<title>The Recursor Cache</title>
7885
<para>As mentioned before, the cache stores partial packets. It also stores not the <command>Time To Live</command> of records, but in fact the <command>Time To Die</command>. If the cache contains data, but it is expired, that data should not be deemed present. This bit of PowerDNS has proven tricky, leading to deadlocks in the past.</para>
7886
7887
<para>There are some other very tricky things to deal with. For example, through a process called <command>more details</command>, a domain might have more nameservers than listed in its parent zone. So, there might only be two nameservers for <literal><command>powerdns.com.</command></literal> in the <command><literal>com.</literal></command> zone, but the <command><literal>powerdns.com</literal></command> zone might list more.</para>
7888
7889
<para>This means that the cache should not, when talking to the <command><literal>com.</literal></command> servers later on, overwrite these four nameservers with only the two copies the <command><literal>com.</literal></command> servers pass us.</para>
7890
7891
<para>However, in other cases (like for example for SOA and CNAME records), new data should overwrite old data.</para>
7892
<para>Note that PowerDNS deviates from RFC 2181 (section 5.4.1) in this respect.</para>
7893
7894
</sect2>
7895
<sect2>
7896
<title>Some small things</title>
7897
<para>The server-side part of PowerDNS (<literal>pdns_recursor.cc</literal>), which listens to queries by end-users, is fully IPv6 capable using the ComboAddress class. This class is in fact a union of a <literal>struct sockaddr_in</literal> and a <literal>struct sockaddr_in6</literal>. As long as the <literal>sin_family</literal> (or <literal>sin6_family</literal>) and <literal>sin_port</literal> members are in the same place, this works just fine, allowing us to pass a ComboAddress*, cast to a <literal>sockaddr*</literal> to the socket functions. For convenience, the ComboAddress also offers a length() method which can be used to indicate the length - either sizeof(sockaddr_in) or sizeof(sockaddr_in6).</para>
7898
7899
<para>Access to the recursor is governed through the NetmaskGroup class, which internally contains Netmaks, which in turn contain a ComboAddress.</para>
7900
</sect2>
7901
</sect1>
6075
7902
</chapter>
6076
7903
<chapter id="replication"><title>Master/Slave operation & replication</title>
6077
7904
6120
7947
Slave operation can also be programmed using several pdns_control commands, see <xref linkend="pdnscontrol">. The 'retrieve' command
6121
7948
is especially useful as it triggers an immediate retrieval of the zone from the configured master.
6122
7949
</para>
7950
<para>
7951
Since 2.9.21, PowerDNS supports multiple masters. For the BIND backend, the native BIND configuration language suffices to specify
7952
multiple masters, for SQL based backends, list all master servers separated by commas in the 'master' field of the domains table.
7953
</para>
6123
7954
<sect2 id=supermaster><title>Supermaster automatic provisioning of slaves</title>
6124
7955
<para>
6125
7956
PDNS can recognize so called 'supermasters'. A supermaster is a host which is master for domains and for which we are to be a slave. When
6145
7976
described in RFC 1996.
6146
7977
</para>
6147
7978
<para>
6148
<para>
6149
7979
<warning>
6150
7980
<para>
6151
7981
Master support is OFF by default, turn it on by adding <command>master</command> to the configuration. The same
6221
8051
support@yourdomain.com should go to.
6222
8052
</para>
6223
8053
</listitem>
8054
</varlistentry>
6224
8055
<varlistentry>
6225
8056
<term>URL</term>
6226
8057
<listitem>
6307
8138
<listitem><para>
6308
8139
Default number of Distributor (backend) threads to start. See <xref linkend="performance">.
6309
8140
</para></listitem></varlistentry>
8141
<varlistentry><term>do-ipv6-additional-processing=...</term>
8142
<listitem><para>
8143
Perform AAAA additional processing.
8144
</para></listitem></varlistentry>
6310
8145
<varlistentry><term>fancy-records=...</term>
6311
8146
<listitem><para>
6312
8147
Process URL and MBOXFW records. See <xref linkend="fancy-records">.
6337
8172
advised to bind to specific interfaces and not use the default 'bind to any'. This causes big problems if you have multiple
6338
8173
IP addresses. Unix does not provide a way of figuring out what IP address a packet was sent to when binding to any.
6339
8174
</para></listitem></varlistentry>
8175
<varlistentry><term>local-ipv6=...</term>
8176
<listitem><para>
8177
Local IPv6 address to which we bind. You can specify multiple addresses separated by commas or whitespace.
8178
</para></listitem></varlistentry>
6340
8179
<varlistentry><term>local-port=...</term>
6341
8180
<listitem><para>
6342
8181
The port on which we listen. Only one port possible.
6378
8217
<listitem><para>
6379
8218
Do not attempt to read the configuration file.
6380
8219
</para></listitem></varlistentry>
8220
<varlistentry><term>no-shuffle</term>
8221
<listitem><para>
8222
Do not attempt to shuffle query results.
8223
</para></listitem></varlistentry>
6381
8224
<varlistentry><term>out-of-zone-additional-processing | --out-of-zone-additional-processing=yes | --out-of-zone-additional-processing=no</term>
6382
8225
<listitem><para>
6383
8226
Do out of zone additional processing. This means that if a malicious user adds a '.com' zone to your server, it is not used for
6387
8230
<listitem><para>
6388
8231
Seconds to store queries with an answer in the Query Cache. See <xref linkend="querycache">.
6389
8232
</para></listitem></varlistentry>
6390
<varlistentry><term>queue-limit=...</term>
6391
<listitem><para>
6392
Maximum number of miliseconds to queue a query. See <xref linkend="performance">.
6393
</para></listitem></varlistentry>
6394
8233
<varlistentry><term>query-local-address=...</term>
6395
8234
<listitem><para>
6396
8235
The IP address to use as a source address for sending queries. Useful if you have multiple IPs and pdns is not bound to the IP address your operating system uses by default for outgoing packets.
6399
8238
<listitem><para>
6400
8239
Hints to a backend that it should log a textual representation of queries it performs. Can be set at runtime.
6401
8240
</para></listitem></varlistentry>
8241
<varlistentry><term>queue-limit=...</term>
8242
<listitem><para>
8243
Maximum number of miliseconds to queue a query. See <xref linkend="performance">.
8244
</para></listitem></varlistentry>
6402
8245
<varlistentry><term>recursive-cache-ttl=...</term>
6403
8246
<listitem><para>
6404
8247
Seconds to store recursive packets in the PacketCache. See <xref linkend="packetcache">.
6407
8250
<listitem><para>
6408
8251
If set, recursive queries will be handed to the recursor specified here. See <xref linkend="recursion">.
6409
8252
</para></listitem></varlistentry>
6410
<varlistentry><term>send-root-referral | --send-root-referral=yes | --send-root-referral=no</term>
8253
<varlistentry><term>send-root-referral | --send-root-referral=yes | --send-root-referral=no | --send-root-referral=lean</term>
6411
8254
<listitem><para>
6412
8255
If set, PowerDNS will send out old-fashioned root-referrals when queried for domains for which it is not authoritative. Wastes some bandwidth
6413
8256
but may solve incoming query floods if domains are delegated to you for which you are not authoritative, but which are queried by broken
6414
8257
recursors. Available since 2.9.19.
8258
</para>
8259
<para>
8260
Since 2.9.21, it is possible to specify 'lean' root referrals, which waste less bandwidth.
6415
8261
</para></listitem></varlistentry>
6416
8262
<varlistentry><term>setgid=...</term>
6417
8263
<listitem><para>
6504
8350
</para>
6505
8351
</chapter>
6506
8352
<chapter id="metrics"><title>Index of all internal metrics</title>
6507
<para></para>
6508
<sect1 id="counters-variables"><title>Counters & variables</title>
8353
<sect1 id="counters-variables"><title>Counters & variables</title>
6509
8354
<para>
6510
8355
A number of counters and variables are set during PDNS operation. These can be queried with the init.d
6511
8356
<command>dump</command>, <command>show</command> and <command>mrtg</command> commands, or viewed with the
6512
8357
webserver.
6513
8358
</para>
8359
<sect2 id="counters">
8360
<title>Counters</title>
8361
<para>
6514
8362
<variablelist>
6515
8363
<varlistentry>
6516
8364
<term>corrupt-packets</term>
6566
8414
</varlistentry>
6567
8415
</variablelist>
6568
8416
</para>
6569
<para>
6570
<sect2><title>Ring buffers</title>
8417
</sect2>
8418
<sect2>
8419
<title>Ring buffers</title>
6571
8420
<para>
6572
8421
Besides counters, PDNS also maintains the ringbuffers. A ringbuffer records events, each new event gets a place
6573
8422
in the buffer until it is full. When full, earlier entries get overwritten, hence the name 'ring'.
6645
8494
</varlistentry>
6646
8495
</variablelist>
6647
8496
</para>
8497
</sect2>
8498
</sect1>
6648
8499
</chapter>
6649
8500
6650
8501
<chapter id="types"><title>Supported record types and their storage</title>
7100
8951
</varlistentry>
7101
8952
</variablelist>
7102
8953
</para>
8954
</sect1>
7103
8955
<sect1 id="pdns-devel-faq"><title>Backend developer HOWTO</title>
7104
8956
<para>
7105
8957
Writing backends without access to the full PDNS source means that you need to write code that can be loaded by PDNS at runtime.
7197
9049
</listitem>
7198
9050
</varlistentry>
7199
9051
<varlistentry>
7200
<term>Q: What I want can't be done from a backend - I need the whole PDNS source</term>
7201
<listitem>
7202
<para>
7203
A: If you require the source, please contact us (pdns@powerdns.com). All commercial licensees receive the source,
7204
for others we may grant exceptions.
7205
</para>
7206
</listitem>
7207
</varlistentry>
7208
<varlistentry>
7209
9052
<term>Q: What is this 'AhuException' I keep reading about?</term>
7210
9053
<listitem>
7211
9054
<para>
7268
9111
to far higher adoption rates. We hope that PowerDNS will soon be included in major Linux and UNIX distributions.
7269
9112
</para>
7270
9113
</listitem>
9114
</varlistentry>
7271
9115
<varlistentry>
7272
9116
<term>Q: How does PowerDNS.COM BV expect to make money now that the nameserver is free?</term>
7273
9117
<listitem>
7286
9130
<para>
7287
9131
In fact, their strategy is a lot like ours in general.
7288
9132
</para>
9133
</listitem>
7289
9134
</varlistentry>
7290
9135
<varlistentry>
7291
9136
<term>Q: Can I buy support contracts for PowerDNS?</term>
7293
9138
<para>
7294
9139
Sure, to do so, please contact us at <email>sales@powerdns.com</email>
7295
9140
</para>
9141
</listitem>
7296
9142
</varlistentry>
7297
9143
<varlistentry>
7298
9144
<term>Q: Will you accept patches? We've added a feature</term>
7325
9171
</varlistentry>
7326
9172
7327
9173
<varlistentry>
7328
<term>Q: We are a Linux/Unix vendor, can we include PowerDNS?
9174
<term>Q: We are a Linux/Unix vendor, can we include PowerDNS?</term>
7329
9175
<listitem>
7330
9176
<para>
7331
9177
A: Please do. In fact, we'd be very happy to work with you to make this happen. Contact <email>ahu@ds9a.nl</email>
7689
9535
<para>
7690
9536
<warning>
7691
9537
<para>
7692
This backend is deprecated! Use the Generic MySQL backend which is better in <emphasis>all</emphasis> respects.
9538
This backend is deprecated! Use the Generic MySQL backend which is better in <command>all</command> respects.
7693
9539
It does support master/slave operation, this backend does not. See <xref linkend="generic-mypgsql-backends">.
7694
9540
</para>
7695
9541
<para>
8071
9917
<para>
8072
9918
<warning>
8073
9919
<para>
8074
If using MySQL with 'slave' support enabled in PowerDNS you <emphasis>must</emphasis> run MySQL with a table engine that supports transactions.
9920
If using MySQL with 'slave' support enabled in PowerDNS you <command>must</command> run MySQL with a table engine that supports transactions.
8075
9921
</para>
8076
9922
</warning>
8077
9923
</para>
8085
9931
create table domains (
8086
9932
id INT auto_increment,
8087
9933
name VARCHAR(255) NOT NULL,
8088
master VARCHAR(20) DEFAULT NULL,
9934
master VARCHAR(128) DEFAULT NULL,
8089
9935
last_check INT DEFAULT NULL,
8090
9936
type VARCHAR(6) NOT NULL,
8091
9937
notified_serial INT DEFAULT NULL,
8123
9969
</programlisting>
8124
9970
</para>
8125
9971
<para>
9972
Zone2sql with the --gmysql flag also assumes this layout is in place.
9973
</para>
9974
<para>
8126
9975
This schema contains all elements needed for master, slave and superslave operation. Depending on which features will be used, the 'GRANT' statements
8127
9976
can be trimmed to make sure PDNS cannot subvert the contents of your database.
8128
9977
</para>
8129
9978
<para>
8130
Zone2sql with the --gmysql flag also assumes this layout is in place.
9979
When using the InnoDB storage engine, we suggest adding the following lines to the 'create table records' command above:
9980
<programlisting>
9981
CONSTRAINT `records_ibfk_1` FOREIGN KEY (`domain_id`) REFERENCES `domains`
9982
(`id`) ON DELETE CASCADE
9983
</programlisting>
9984
</para>
9985
<para>
9986
This automates deletion of records on deletion of a domain from the domains table.
8131
9987
</para>
8132
9988
</sect2>
8133
9989
<sect2><title>PostgresSQL specifics</title>
8137
9993
create table domains (
8138
9994
id SERIAL PRIMARY KEY,
8139
9995
name VARCHAR(255) NOT NULL,
8140
master VARCHAR(20) DEFAULT NULL,
9996
master VARCHAR(128) DEFAULT NULL,
8141
9997
last_check INT DEFAULT NULL,
8142
9998
type VARCHAR(6) NOT NULL,
8143
9999
notified_serial INT DEFAULT NULL,
8197
10053
create table domains (
8198
10054
id NUMBER,
8199
10055
name VARCHAR(255) NOT NULL,
8200
master VARCHAR(20) DEFAULT NULL,
10056
master VARCHAR(128) DEFAULT NULL,
8201
10057
last_check INT DEFAULT NULL,
8202
10058
type VARCHAR(6) NOT NULL,
8203
10059
notified_serial INT DEFAULT NULL,
8482
10338
</listitem>
8483
10339
</varlistentry>
8484
10340
</variablelist>
10341
</para>
10342
</sect2>
8485
10343
<sect2><title>Fancy records</title>
8486
10344
<para>
8487
10345
If PDNS is used with so called 'Fancy Records', the 'MBOXFW' record exists which specifies an email address forwarding instruction,
8649
10507
</programlisting>
8650
10508
Make sure that the assigned id in the domains table matches the domain_id field in the records table!
8651
10509
</para>
10510
</sect2>
8652
10511
</sect1>
8653
10512
8654
10513
<sect1 id="oracle"><Title>Oracle backend</title>
8808
10667
create table Domains (
8809
10668
ID number(11) NOT NULL,
8810
10669
NAME VARCHAR(255) NOT NULL,
8811
MASTER VARCHAR(20) DEFAULT NULL,
10670
MASTER VARCHAR(128) DEFAULT NULL,
8812
10671
LAST_CHECK INT DEFAULT NULL,
8813
10672
TYPE VARCHAR(6) NOT NULL,
8814
10673
NOTIFIED_SERIAL INT DEFAULT NULL,
8858
10717
</sect1>
8859
10718
8860
10719
<sect1 id="gsqlite">
8861
<title>Generic SQLite backend</title>
10720
<title>Generic SQLite backend (2 and 3)</title>
8862
10721
<para>
8863
10722
<table>
8864
10723
<title>Generic SQLite backend capabilities</title>
8882
10741
<para>
8883
10742
As this is a generic backend, built on top of the gSql framework, you can specify all queries as documented in <link linkend="generic-mypgsql-backends">Generic MySQL and PgSQL backends</link>.
8884
10743
</para>
10744
<para>
10745
SQLite exists in two incompatible versions, numbered 2 and 3, and from 2.9.21 onwards, PowerDNS supports both. It is recommended to go with version 3
10746
as it is newer, has better performance and is actively maintained.
10747
</para>
8885
10748
<sect2>
8886
10749
<title>Compiling the SQLite backend</title>
8887
10750
<para>
8889
10752
You can download these from <ulink url="http://www.sqlite.org/download.html">http://www.sqlite.org/download.html</ulink>, or you can use packages (if your distribution provides those).
8890
10753
</para>
8891
10754
<para>
8892
When you've installed the library you can use: <command>./configure --with-modules="gsqlite"</command> to configure PowerDNS to use the SQLite backend.
8893
Compilation can then proceed as usual.
10755
When you've installed the library you can use: <command>./configure --with-modules="gsqlite"</command> or
10756
<command>./configure --with-modules="gsqlite3"</command> to configure PowerDNS to use the SQLite backend.
10757
Compilation can then proceed as usual.
8894
10758
</para>
8895
10759
<para>
8896
10760
SQLite is included in most PowerDNS binary releases.
8904
10768
8905
10769
<programlisting>
8906
10770
create table domains (
8907
id INTEGER PRIMARY KEY,
8908
name VARCHAR(255) NOT NULL,
8909
master VARCHAR(20) DEFAULT NULL,
8910
last_check INTEGER DEFAULT NULL,
8911
type VARCHAR(6) NOT NULL,
10771
id INTEGER PRIMARY KEY,
10772
name VARCHAR(255) NOT NULL,
10773
master VARCHAR(128) DEFAULT NULL,
10774
last_check INTEGER DEFAULT NULL,
10775
type VARCHAR(6) NOT NULL,
8912
10776
notified_serial INTEGER DEFAULT NULL,
8913
10777
account VARCHAR(40) DEFAULT NULL
8914
10778
);
8943
10807
<para>
8944
10808
After you have created the database you probably want to fill it with data.
8945
10809
If you have a BIND zonefile it's as easy as: <command>zone2sql --zone=myzonefile --gmysql | sqlite powerdns.sqlite</command>, but
8946
you can also use AXFR (or insert data manually if you have too much time ;)).
10810
you can also use AXFR (or insert data manually).
8947
10811
</para>
10812
<para>
10813
To communicate with a SQLite database, use either the 'sqlite' or 'sqlite3' program, and feed it SQL.
10814
</para>
8948
10815
</sect2>
8949
10816
<sect2>
8950
10817
<title>Using the SQLite backend</title>
8954
10821
<para>
8955
10822
<programlisting>
8956
10823
# in pdns.conf
8957
launch=gsqlite
8958
gsqlite-database=<path to your SQLite database>
10824
launch=gsqlite # or gsqlite3
10825
gsqlite-database=<path to your SQLite database> # or gsqlite3-database
8959
10826
</programlisting>
8960
10827
</para>
8961
10828
<para>
9072
10939
</table>
9073
10940
</para>
9074
10941
<para>
9075
<note>
9076
<para>
9077
There is also the Bind2backend which works exactly like this backend but is far more experimental. In the future it supplant the bindbackend.
9078
</para>
9079
</note>
9080
</para>
9081
<para>
9082
10942
The BindBackend started life as a demonstration of the versatility of PDNS but quickly gained in importance when there appeared to be demand
9083
10943
for a Bind 'workalike'.
9084
10944
</para>
9101
10961
<listitem>
9102
10962
<para>
9103
10963
Loads the 'example.com' zone which can be queried to determine if PowerDNS is functioning without configuring
9104
database backends.
10964
database backends. This feature is no longer supported from 2.9.21 onwards.
9105
10965
</para>
9106
10966
</listitem>
9107
10967
</varlistentry>
9148
11008
If <command>bind-check-interval</command> is specified as zero, no checks will be performed until the <command>pdns_control reload</command>
9149
11009
is given.
9150
11010
</para>
11011
</sect2>
9151
11012
<sect2 id="bind-control-commands"><title>Pdns_control commands</title>
9152
11013
<para>
9153
11014
<variablelist>
9206
11067
In the future, this may be improved so the old zone remains available should parsing fail.
9207
11068
</para>
9208
11069
</sect3>
11070
</sect2>
9209
11071
<sect2><title>Commands</title>
9210
11072
<para>
9211
11073
<command>pdns_control</command> offers commands to communicate instructions to PowerDNS. These are detailed here.
9344
11206
may be outdated!
9345
11207
</para>
9346
11208
</warning>
11209
</para>
9347
11210
<para>
9348
11211
The main author for this module is Norbert Sendetzky who also has his own <ulink url="http://www.linuxnetworks.de/pdnsldap/index.html">PowerDNS-LDAP page</ulink>.
9349
11212
</para>
9731
11594
PDNS breaks strict RFC compatability by not always checking for the presence of a SOA record first. This is unlikely to lead to
9732
11595
problems though.
9733
11596
</para>
11597
</sect1>
9734
11598
</appendix>
9735
11599
<appendix id="backend-writers-guide"><title>Backend writers' guide</title>
9736
11600
<para>
9747
11611
exception of MySQL), you must make sure that you do find answers which differ only in case.
9748
11612
</para></warning>
9749
11613
</para>
11614
<para>
11615
<warning><para>
11616
PowerDNS may instantiate multiple instances of your backend, or destroy existing copies and instantiate new ones. Backend code
11617
should therefore be thread-safe with respect to its static data. Additionally, it is wise if instantiation is a fast operation,
11618
with the possible exception of the first construction.
11619
</para></warning>
11620
</para>
9750
11621
<sect1 id="simple-backends"><title>Simple read-only native backends</title>
9751
11622
<para>
9752
11623
Implementing a backend consists of inheriting from the DNSBackend class. For read-only backends, which do not support slave operation,
9882
11753
class RandomLoader
9883
11754
{
9884
11755
public:
9885
Loader()
11756
RandomLoader()
9886
11757
{
9887
11758
BackendMakers().report(new RandomFactory);
9888
11759
9910
11781
that by setting <command>random-hostname</command>.
9911
11782
</para>
9912
11783
<para>
9913
NOTE: this simple backend neglects to handle case properly! For a more complete example, see the full pdns-dev distribution as found on
9914
<ulink url="http://www.powerdns.com/pdns">the website</ulink>.
11784
NOTE: this simple backend neglects to handle case properly!
9915
11785
</para>
9916
11786
</sect2>
9917
11787
<sect2><title>Interface definition</title>
10022
11892
</varlistentry>
10023
11893
10024
11894
<varlistentry>
10025
<term>bool list(int domain_id)
11895
<term>bool list(int domain_id)</term>
10026
11896
<listitem>
10027
11897
<para>
10028
11898
Initiates a list of the indicated domain. Records should then be made available via the <function>get()</function> method.
10397
12267
</para>
10398
12268
<para>
10399
12269
Supermaster/superslave is a complicated concept, if this is all unclear see <xref linkend="supermaster">.
12270
</para>
10400
12271
</sect2>
10401
12272
</sect1>
10402
12273
<sect1 id="master-backends"><title>Read/write master-capable backends</title>
10495
12366
<para>
10496
12367
The FreeBSD Boost include files are installed in <filename>/usr/local/include</filename>, so prefix <command>CXXFLAGS=-I/usr/local/lib</command>
10497
12368
to your <command>./configure</command> invocation.
12369
</para>
10498
12370
</sect2>
10499
12371
<sect2 id="unix-linux"><title>Linux</title>
10500
12372
<para>
10528
12400
<sect1 id="on-windows"><title>Compiling PowerDNS on Windows</title>
10529
12401
<para>
10530
12402
By Michel Stol (<email>michel@powerdns.com</email>).
12403
</para>
10531
12404
<sect2><title>Assumptions</title>
10532
12405
<para>
10533
12406
I will assume these things from you:
10638
12511
</para>
10639
12512
</sect4>
10640
12513
10641
<sect3>
12514
<sect4>
10642
12515
<title>Installing pthreads for Windows</title>
10643
12516
10644
12517
<para>
10656
12529
The library is now installed, we still have to tell Visual C++ where it's located though, more
10657
12530
on that later.
10658
12531
</para>
10659
</sect3>
12532
</sect4>
12533
</sect3>
10660
12534
10661
12535
</sect2>
10662
12536
10817
12691
<para>
10818
12692
First add the include directory, to do this you have to select <guilabel>Include files</guilabel>
10819
12693
from the <guilabel>Show directories for:</guilabel> combobox. Then press the <guibutton>New</guibutton>
10820
button and browse to the <emphasis>include</emphasis> directory of pthreads (ie. <filename>C:\pthreads\include</filename>).
12694
button and browse to the <command>include</command> directory of pthreads (ie. <filename>C:\pthreads\include</filename>).
10821
12695
</para>
10822
12696
10823
12697
<para>
10824
Then switch to <guilabel>Library files</guilabel> and add the <emphasis>library</emphasis> directory
12698
Then switch to <guilabel>Library files</guilabel> and add the <command>library</command> directory
10825
12699
(ie. <filename>C:\pthreads\lib</filename>) using the same method as above.
10826
12700
</para>
10827
12701
</sect4>
11006
12880
11007
12881
</sect2>
11008
12882
</sect1>
12883
</appendix>
11009
12884
<appendix id="license"><title>PowerDNS license (GNU General Public License version 2)</title>
11010
12885
<para>
11011
12886
GNU GENERAL PUBLIC LICENSE
Loggerhead is a web-based interface for Breezy
Version: 2.0.1