8 It is a book about a Spanish guy called Manual. You should read it.
12 ----------------------------------------------------------------------
16 1. The PowerDNS dynamic nameserver
18 1.1. Function & design of PDNS
20 1.2. About this document
48 1.3.13. Version 2.9.3a
58 1.3.18. Version 2.7 and 2.7.1
80 1.3.29. Version 2.0 Release Candidate 2
82 1.3.30. Version 2.0 Release Candidate 1
84 1.3.31. Version 1.99.12 Prerelease
86 1.3.32. Version 1.99.11 Prerelease
88 1.3.33. Version 1.99.10 Prerelease
90 1.3.34. Version 1.99.9 Early Access Prerelease
92 1.3.35. Version 1.99.8 Early Access Prerelease
94 1.3.36. Version 1.99.7 Early Access Prerelease
96 1.3.37. Version 1.99.6 Early Access Prerelease
98 1.3.38. Version 1.99.5 Early Access Prerelease
100 1.3.39. Version 1.99.4 Early Access Prerelease
102 1.3.40. Version 1.99.3 Early Access Prerelease
104 1.3.41. Version 1.99.2 Early Access Prerelease
106 1.3.42. Version 1.99.1 Early Access Prerelease
110 1.5. Acknowledgements
112 2. Installing on Unix
114 2.1. Possible problems at this point
116 2.2. Testing your install
118 2.2.1. Typical errors
120 2.3. Running PDNS on unix
122 3. Installing on Microsoft Windows
124 3.1. Configuring PDNS on Microsoft Windows
126 3.2. Running PDNS on Microsoft Windows
128 4. Configure database connectivity
130 4.1. Configuring MySQL
132 4.1.1. Common problems
134 5. Dynamic resolution using the PipeBackend
136 5.1. Deploying the PipeBackend with the BindBackend
138 6. Logging & Monitoring PDNS performance
142 6.2. Via init.d commands
144 6.3. Operational logging using syslog
146 7. Security settings & considerations
150 7.1.1. Running as a less privileged identity
152 7.1.2. Jailing the process in a chroot
158 9. Performance related settings
164 10. Migrating to PDNS
172 12. PowerDNS resolver/recursing nameserver
174 12.1. pdns_recursor settings
176 12.1.1. Verisign weirdness
182 13. Master/Slave operation & replication
184 13.1. Native replication
186 13.2. Slave operation
188 13.2.1. Supermaster automatic provisioning of
191 13.3. Master operation
193 14. Fancy records for seamless email and URL integration
195 15. Index of all settings
197 16. Index of all internal metrics
199 16.1. Counters & variables
203 17. Supported record types and their storage
205 18. HOWTO & Frequently Asked Questions
207 18.1. Getting support, free and paid FAQ
209 18.2. Using and Compiling PowerDNS FAQ
211 18.3. Backend developer HOWTO
213 18.4. About PowerDNS.COM BV, 'the company'
215 A. Backends in detail
219 A.1.1. PipeBackend protocol
223 A.2.1. Configuration settings
229 A.4. MySQL PDNS backend
233 A.5. Generic MySQL and PgSQL backends
235 A.5.1. MySQL specifics
237 A.5.2. PostgresSQL specifics
239 A.5.3. Basic functionality
241 A.5.4. Master/slave queries
245 A.5.6. Settings and specifying queries
247 A.5.7. Native operation
249 A.5.8. Slave operation
251 A.5.9. Superslave operation
253 A.5.10. Master operation
255 A.6. Generic Oracle backend
257 A.6.1. Setting up Oracle for use with PowerDNS
259 A.7. Generic SQLite backend
261 A.7.1. Compiling the SQLite backend
263 A.7.2. Setting up the database
265 A.7.3. Using the SQLite backend
269 A.9. Bind zone file backend
273 A.9.2. Pdns_control commands
277 A.9.4. Master/slave configuration
295 B.3. Modules & Backends
297 B.4. How PDNS translates DNS queries into backend queries
299 C. Backend writers' guide
301 C.1. Simple read-only native backends
303 C.1.1. A sample minimal backend
305 C.1.2. Interface definition
307 C.2. Reporting errors
309 C.3. Declaring and reading configuration details
311 C.4. Read/write slave-capable backends
313 C.4.1. Supermaster/Superslave capability
315 C.5. Read/write master-capable backends
317 D. Compiling PowerDNS
319 D.1. Compiling PowerDNS on Unix
333 D.2. Compiling PowerDNS on Windows
339 D.2.3. Nullsoft Installer
341 D.2.4. Setting up the build-environment
347 E. PowerDNS license (GNU General Public License version 2)
353 A-1. PipeBackend capabilities
355 A-2. MySQL backend capabilities
357 A-3. Random Backend capabilities
359 A-4. MySQL backend capabilities
361 A-5. Generic PgSQL and MySQL backend capabilities
363 A-6. Oracle backend capabilities
365 A-7. Generic SQLite backend capabilities
367 A-8. DB2 backend capabilities
369 A-9. Bind zone file backend capabilities
371 A-10. ODBC backend capabilities
373 A-11. LDAP backend capabilities
375 C-1. DNSResourceRecord class
379 C-3. DomainInfo struct
381 ----------------------------------------------------------------------
383 Chapter 1. The PowerDNS dynamic nameserver
385 The PowerDNS daemon is a versatile nameserver which supports a large
386 number of backends. These backends can either be plain zonefiles or be
387 more dynamic in nature.
389 Prime examples of backends include relational databases, but also
390 loadbalancing and failover algorithms.
392 The company is called PowerDNS BV, the nameserver daemon is called PDNS.
394 ----------------------------------------------------------------------
396 1.1. Function & design of PDNS
398 PDNS is an authoritative only nameserver. It will answer questions about
399 domains it knows about, but will not go out on the net to resolve queries
400 about other domains. However, it can use a recursing backend to provide
403 When PDNS answers a question, it comes out of the database, and can be
404 trusted as being authoritative. There is no way to pollute the cache or to
407 PDNS has been designed to serve both the needs of small installations by
408 being easy to setup, as well as for serving very large query volumes on
409 large numbers of domains.
411 Another prime goal is security. By the use of language features, the PDNS
412 source code is very small (in the order of 10.000 lines) which makes
413 auditing easy. In the same way, library features have been used to
414 mitigate the risks of buffer overflows.
416 Finally, PDNS is able to give a lot of statistics on its operation which
417 is both helpful in determining the scalability of an installation as well
418 as for spotting problems.
420 ----------------------------------------------------------------------
422 1.2. About this document
424 If you are reading this document from disk, you may want to check
425 http://doc.powerdns.com for updates. The PDF version is available on
426 http://doc.powerdns.com/pdf, a text file is on
427 http://doc.powerdns.com/txt/.
429 ----------------------------------------------------------------------
433 Before proceeding, it is advised to check the release notes for your PDNS
434 version, as specified in the name of the distribution file.
436 ----------------------------------------------------------------------
438 1.3.1. Version 2.9.16
440 The 'it must still be Friday somewhere' release. Massive number of fixes,
441 portability improvements and the new Geobackend by Mark Bergsma & friends.
445 * The Geobackend which makes it possible to send different answers to
446 different IP ranges. Initial documentation can be found in
447 pdns/modules/geobackend/README.
449 * qgen query generation tool. Nearly completely undocumented and hard to
450 build too, it requires Boost. But very spiffy. Use cd pdns; make qgen
455 * The most reported bug ever, zone2sql required the inclusion of
456 unistd.h, except on Debian unstable.
458 * PowerDNS tried to listen on its control "pipe" which does not work.
459 Probably harmless, but might have caused some oddities.
461 * The Packet Cache did not always set its TTL immediately, causing some
462 packets to be inserted, even when running with the cache disabled
465 * Valgrind found some unitialized reads, causing bogus values in the
466 priority field when it was not needed
468 * Valgrind found a bug in MTasker where we used delete instead of
471 * SOA serials and other parameters are unsigned. This means that very
472 large SOA serial numbers would be messed up (Michel Stol, Stefano
475 * PowerDNS left its controlsocket around after exit and reported
476 confusing errors if a socket was already in use.
478 * The recursor proxy did not work on big endian systems like SPARC and
479 some MIPS processors (Remco Post)
481 * We no longer dump core on processing LOC records on UltraSPARC (Andrew
482 Mulholland supplied a testing machine)
486 * MySQL can now connect to a specified port again (Chris Anderton)
488 * When running chroot()ed and with master or slave support active,
489 PowerDNS needs to resolve domain names to find slaves. This in turn
490 may require access to certain libraries. Previously, these needed to
491 be available in the chroot directory but by forcing an initial lookup,
492 these libraries are now loaded before the chrooting.
494 * pdns_recursor was very slow after having done a larger number of
495 queries because of the checks to see if a query should be throttled.
496 This is now done using a set which is a lot faster than the previous
497 full sequential scan.
499 * The throttling code may not have throttled as much as was configured.
501 * Yet another big LDAP update. The LDAP backend now loadbalances
502 connections over several hosts (Norbert Sendetzky)
504 * Updated b.root-servers.net address in the recursor
506 ----------------------------------------------------------------------
508 1.3.2. Version 2.9.15
510 This release fixes up some of the shortcomings in 2.9.14, and adds some
515 * allow-recursion-override was on by default, it was meant to be off.
517 * Logging was still off in daemon mode, fixed.
519 * debian/rules forgot to build an sqllite package
521 * Recursor accidentally linked in MySQL - this was the result of an
522 experiment with a persistent recursor cache.
524 * The PowerDNS recursor had stability problems. It now sorts nameservers
525 (roughly) by responsiveness. The 'roughly' part upset the sorting
526 algorithm used, the speeds being sorted on changed during sorting.
528 * The recursor now outputs the nameserver average response times in
531 * LDAP compiles again.
535 * zone2sql can now accept - as a filename which causes it to read stdin.
536 This allows the following to work: dig axfr ds9a.nl | zone2sql
537 --gmysql --zone=- | mysql pdns, which is a nice way to import a zone.
539 * zone2sql now ignores duplicate SOA records which are identical - which
540 also makes the above possible.
542 * Remove libpqpp dependencies - since we now use the native C API for
545 ----------------------------------------------------------------------
547 1.3.3. Version 2.9.14
549 Big release with the fix for the all important 2^30 seconds problem and a
552 * errno problems would cause compilation problems when using LDAP
555 * The Generic SQL backend could cause crashes on PostgreSQL when using
556 pdns_control notify (Georg Bauer)
558 * Debian compatible init.d script (Wichert Akkerman)
560 * If using the master or slave features, pdns had the notion of eternity
561 ending in 2038, except that due to a thinko, eternity ended out to be
562 the 10th of January 2004. This caused a loop to timeout immediately.
563 Many thanks to Jasper Spaans for spotting the bug within five minutes.
565 * Parts of the SOA field were not cannonicalized
567 * The loglevel could in fact cause nothing to be logged (Norbert
572 * The recursor now chooses the fastest nameserver, which causes a big
575 * LDAP now has different lookup models
577 * Cleanups, better load distribution, better exception handling,
578 zone2ldap improvements
580 * The recursor was somewhat chatty about TCP connections
582 * PostgreSQL now only depends on the C API and not on the deprecated C++
585 * PowerDNS can now fully overrule external zones when doing recursion.
588 ----------------------------------------------------------------------
590 1.3.4. Version 2.9.13
592 Big news! Windows is back! Our great friend Michel Stol found the time to
593 update the PowerDNS code so it works again under windows.
595 Furthermore, big thanks go out to Dell who quickly repaired my trusty
600 * Generic SQLite support added
602 * Removed the ODBC backend, replaced it by the Generic ODBC Backend,
603 which has all the cool configurability of the Generic MySQL and
606 * The PowerDNS Recursor now runs as a Service. It defaults to running on
607 port 5300, PowerDNS itself is configured to expect the Recursor on
610 * The PowerDNS Service is now known as 'PowerDNS' to Windows.
612 * The Installer was redone, this time with NSIS2.
614 * General updates and fixes.
618 Note There appears to be a problem with PowerDNS on Red Hat 7.3 with GCC
619 2.96 and self-compiled binaries. The symptoms are that PowerDNS works
620 on the foreground but fails as a daemon. We're working on it.
622 If you do note problems, let the list know, if you don't, please do
623 so as well. Tell us if you use the RPM or compiled yourself.
625 It is known that not compiling in MySQL support helps solve the
626 problem, but then you don't have MySQL.
628 There have been a number of reports on MySQL connections being dropped on
629 FreeBSD 4.x, which sometimes causes PowerDNS to give up and reload itself.
630 To combat this, MySQL error messages have been improved in some places in
631 hopes of figuring out what is up. The initial indication is that MySQL
632 itself sometimes terminates the connection and, amazingly, that switching
633 to a Unix domain socket instead of TCP solves the problem.
637 * allow-axfr-ips did not work for individual IP addresses (bug & fix by
642 * Opteron support! Thanks to Jeff Davey for providing a shell on an
643 Opteron. The fixes should also help PowerDNS on other platforms with a
646 Btw, the PowerDNS team has a strong desire for an Opteron :-)
648 * pdns_recursor jumbles answers now. This means that you can do poor
649 man's roundrobin by supplying multiple A, MX or AAAA records for a
650 service, and get a random one on top each time. Interestingly, this
651 feature appeared out of nowhere, this change was made to the
652 authoritative code but due to the wonders of code-reuse had an effect
653 on pdns_recursor too.
655 * Big LDAP cleanup. Support for TLS was added. Zone2LDAP also gained the
656 ability to generate ldif files containing a tree or a list of entries.
659 * Zone2sql is now somewhat clearer when reporting malformed line errors
660 - it did not always include the name of the file causing a problem,
661 especially for big installations. Problem noted by Thom May.
663 * pdns_recursor now survives the expiration of all its root records,
664 most often caused by prolonged disconnection from the net.
666 ----------------------------------------------------------------------
668 1.3.5. Version 2.9.12
670 Release rich in features. Work on Verisign oddities, addition of SQLite
671 backend, pdns_recursor maturity.
675 * --version command (requested by Mike Benoit)
677 * delegation-only, a Verisign special. See Section 12.1.1.
679 * Generic SQLite support, by Michel 'Who da man?' Stol. See Section A.7.
681 * init.d script for pdns_recursor
683 * Recursor now actually purges its cache, saving memory.
685 * Slave configuration now no longer falls over when presented with a
688 * Bindbackend2 now has supermaster support (Mark Bergsma, untested)
690 * Answers are now shuffled! It turns out a few recursors don't do
691 shuffling (pdns_recursor, djbdns), so we do it now. Requested by Jorn
692 Ekkelenkamp of ISP-Services. This means that if you have multiple IP
693 addresses for one host, they will be returned in differing order every
698 * 0.0.0.0/0 didn't use to work (Norbert Sendetzky)
700 * pdns_recursor would try to resolve IP address which to bind to,
701 potentially causing chicken/egg problem
703 * gpgsql no longer reports as gmysql (Sherwin Daganoto)
705 * SRV would not be parsed right from disk (Christof Meerwald)
707 * An AXFR from a zone hosted on the LDAP backend no longer transmits all
708 the reverse entries too (Norbert Sendetzky)
710 * PostgreSQL backend now does error checking. It would be a bit too
713 Improvements, cleanups:
715 * PowerDNS now reports the numerical IP addresses it binds to instead of
716 the, possibly, alphanumeric names the operator passed.
718 * Removed only-soa hackery (noticed by Norbert Sendetzky)
720 * Debian packaging fixes (Wichert Akkerman)
722 * Some parameter descriptions were improved.
724 * Cleanups by Norbert: getAuth moved to chopOff, arguments::contains
725 massive cleanup, more.
727 ----------------------------------------------------------------------
729 1.3.6. Version 2.9.11
731 Yet another iteration, hopefully this will be the last silly release.
733 Warning There has been a change in behaviour whereby disable-axfr does
734 what it means now! From now on, setting allow-axfr-ips
735 automatically disables AXFR from unmentioned subnets.
737 This release enables AXFR again, disable-axfr did the opposite of what it
738 claimed. Furthermore, the pdns_recursor now cleans its cache, which should
739 save some memory in the long run. Norbert contributed some small LDAP work
740 which should come in useful in the future.
742 ----------------------------------------------------------------------
744 1.3.7. Version 2.9.10
746 Small bugfixes, LDAP update. Released 3rd of July 2003. Apologies for the
747 long delay, real life keeps interfering.
749 Warning Do not use or try to use 2.9.9, it was a botched release!
751 Warning There has been a change in behaviour whereby disable-axfr does
752 what it means now! From now on, setting allow-axfr-ips
753 automatically disables AXFR from unmentioned subnets.
755 * 2.9.8 was prone to crash on adding additional records. Thanks to
756 excellent debugging by PowerDNS users worldwide, the bug was found
757 quickly and is in fact present in all earlier PowerDNS releases, but
758 for some reason doesn't cause crashes there.
760 * Notifications now jump in front of the queue of domains that need to
761 be checked for changes, giving much greater perceived performance.
762 This is needed if you have tens of thousands of slave domains and your
763 master server is on a high latency link. Thanks to Mark Jeftovic of
764 EasyDNS for suggesting this change and testing it on their platform.
766 * Dean Mills reported that PowerDNS does confusing logging about
767 changing GIDs and UIDs, fixed. Cosmetic only.
769 * pdns_recursor may have logged empty lines for some users, fixed.
770 Solution suggested by Norbert Sendetzky.
772 * LDAP: DNS TTLs were random values (Norbert Sendetzky, Stefan
773 Pfetzing). New ldap-default-ttl option.
775 * LDAP: Now works with OpenLDAP 2.1 (Norbert Sendetzky)
777 * LDAP: error handling for invalid MX records implemented (Norbert
780 * LDAP: better exception handling (Norbert Sendetzky)
782 * LDAP: code cleanup of lookup() (Norbert Sendetzky)
784 * LDAP: added support for scoped searches (Norbert Sendetzky)
786 ----------------------------------------------------------------------
790 Queen's day release! 30th of April 2003.
792 Added support for AIX, fixed negative SOA caching. Some other cleanups.
793 Not a major release but enough reasons to upgrade.
797 * Recursor had problems expiring negatively cached entries, which wasted
798 memory and also led to the continued non-existence of hosts that since
799 had come into existence.
801 * The Generic SQL backends did not lowercase the names of records, which
802 led to new records not being found by case sensitive databases
803 (notably PostgreSQL). Found by Volker Goetz.
805 * NS queries for zones for which we did not carry authority, but only
806 had delegation information, had their NS records in the wrong section.
807 Minor detail, but a standards violation on etheless. Spotted by
812 * Removed crypt.h dependency from powerldap.hh, which was a problem on
813 some platforms (Richard Arends)
815 * PowerDNS can't parse so called binary labels which we now detect and
816 ignore, after printing a warning.
818 * Specifying allow-axfr-ips now automatically disables AXFR for all
819 non-mentioned addresses.
821 * A Solaris ready init.d script is now part of the tar.gz (contributed,
824 * Added some fixes to PowerDNS can work on AIX (spotted by Markus
827 * Norbert Sendetzky contributed zone2ldap.
829 * Everybody's favorite compiler warning from zone2sql.cc was removed!
831 * Recursor now listens on TCP!
833 ----------------------------------------------------------------------
837 Released on 2003-03-20.
839 This is a sweeping release in the sense of cleanup. There are some new
840 features but mostly a lot of cleanup going on. Hiding inside is the
841 bind2backend, the next generation of the bind backend. A work in progress.
842 Those of you with overlapping zones, as mentioned in the changelog of
843 2.9.6, are invited to check it out by replacing launch=bind by
844 launch=bind2 and renaming all bind- parameters to bind2-. Be aware that if
845 you run with many small zones, this backend is faster, but if you run with
846 a few large ones, it is slower. This will improve.
850 * Mark Bergsma contributed query-local-address which allows the operator
851 to select which source address to use. This is useful on servers with
852 multiple source addresses and the operating system selecting an
853 unintended one, leading to remotes denying access.
855 * PowerDNS can now perform AAAA additional processing optionally, turned
856 on by setting do-ipv6-additional-processing. Thanks to Stephane
857 Bortzmeyer for pointing out the need.
859 * Bind2backend, which is almost in compliance with the new IETF
860 AXFR-clarify (some would say 'redefinition') draft.
862 This backend is not ready for primetime but you may want to try it if
863 you currently have overlapping zones and note problems. An overlapping
864 zone would be having "ipv6.powerdns.com" and "powerdns.com" zones on
869 * Zone2sql would happily try to read from a directory and not give a
870 useful error about this.
872 * PowerDNS now reports the case where it can't figure out any IP address
873 of slave nameservers for a zone
875 * Removed receiver-threads setting which was experimental and in fact
876 only made things worse.
878 * LDAP backend updates from its author Norbert Sendetzky. Reverse
879 lookups should work now too.
881 * An error message about unparseable packets did not include the
882 originating IP address (fixed by Mark Bergsma)
884 * PowerDNS can now be started via path resolution while running with a
885 guardian. Suggested by Maurice Nonnekes.
887 * pdns_recursor moved to sbin (reported by Norbert Sendetzky)
889 * Retuned some logger errorlevels, a lot of master/slave chatter was
890 logged as 'Error'. Reported by Willem de Groot.
894 * zone2sql did not remove trailing dots in SOA records.
896 * ldapbackend did not include utility.hh which caused compilation
897 problems on Solaris (reported by Remco Post)
899 * pdns_control could leave behind remnants in case PowerDNS was not
900 running (reported by dG)
902 * Incoming AXFR did not work on Solaris and other big-endian systems
903 (Willem de Groot helped debugging this long standing problem).
905 * Recursor could crash on convoluted CNAME loops. Thanks to Dan Faerch
906 for delivering coredumps.
908 * Silly 'wuh' debugging output in zone2sql and bindbackend removed
909 (spotted by Ivo van der Wijk)
911 * Recursor neglected to differentiate between negative cache of NXDOMAIN
912 and NOERROR, leading to problems with IPv6 enabled Windows clients.
913 Thanks to Stuart Walsh for reporting this and testing the fix.
915 * PowerDNS set the 'aa' bit on serving NS records in a zone for which it
916 was authoritative. Most implementations drop the 'aa' bit in this case
917 and Stephane Bortzmeyer informed us of this. PowerDNS now also drops
918 the 'aa' bit in this case.
920 * The webserver tended to fail after prolonged operation on FreeBSD,
921 this was due to an uninitialised timeout, other platforms were lucky.
922 Thanks to G.P. de Boer for helping debug this.
924 * getAnswers() in dnspacket.cc could be forced to read bytes beyond the
925 end of the packet, leading to crashes in the PowerDNS recursor. This
926 is an ongoing project that needs more work. Reported by Dan Faerch,
927 with a coredump proving the problem.
929 ----------------------------------------------------------------------
931 1.3.10. Version 2.9.6
933 Two new backends - Generic ODBC (windows only) and LDAP. Furthermore, a
934 few important bugs have been fixed which may have hampered sites seeing a
935 lot of outgoing zonetransfers. Additionally, the pdns recursor now has
936 'query throttling' which is pretty cool. In short this makes sure that
937 PowerDNS does not send out heaps of queries if a nameserver is unable to
938 provide an answer. Many operators of authoritative setups are all too
939 aware of recursing nameservers that hammer them for zones they don't have,
940 PowerDNS won't do that anymore now, no matter what clients request of it.
942 Warning There is an unresolved issue with the BIND backend and
943 'overlapping' slave zones. So if you have 'example.com' and also
944 have a separate slave zone called 'external.example.com', things
945 may go wrong badly. Thanks to Christian Laursen for working with
946 us a lot in finding this issue. We hope to resolve it soon.
948 * BIND Backend now honours notifies, code to support this was
949 accidentally left out. Thanks to Christian Laursen for noticing this.
951 * Massive speedup for those of you using the slightly deprecated MBOXFW
952 records. Thanks to Jorn of ISP Services for helping and testing this
955 * $GENERATE had an off-by-one bug where it would omit the last record to
956 be generated (Christian Laursen)
958 * Simultaneous AXFRs may have been problematic on some backends. Thanks
959 to Jorn of ISP-Services again for helping us resolve this issue.
961 * Added LDAP backend by Norbert Sendetzky, see Section A.12.
963 * Added Generic ODBC backend for Windows by Michel Stol.
965 * Simplified 'out of zone data' detection in incoming AXFR support,
966 hopefully removing a case sensitivity bug there. Thanks again to
967 Christian Laursen for reporting this issue.
969 * $include in-zonefile was broken under some circumstances, losing the
970 last character of a filename. Thanks to Joris Vandalon for noticing
973 * The zoneparser was more case-sensitive than BIND, refusing to accept
974 'in' as well as 'IN'. Thanks to Joris Vandalon for noticing this.
976 ----------------------------------------------------------------------
978 1.3.11. Version 2.9.5
980 Released on 2002-02-03.
982 This version is almost entirely about recursion with major changes to both
983 the pdns recursor, which is renamed to 'pdns_recursor' and to the main
984 PowerDNS binary to make it interact better with the recursing component.
986 Sadly, due to technical reasons, compiling the pdns recursor and pdns
987 authoritative nameserver into one binary is not immediately possible.
988 During the release of 2.9.4 we stated that the recursing nameserver would
989 be integrated in the next release - this won't happen now.
991 However, this turns out to not be that bad at all. The recursor can now be
992 restarted without having to restart the rest of the nameserver, for
993 example. Cooperation between the both halves of PDNS is also almost
994 seamless. As a result, 'non-lazy recursion' has been dropped. See Chapter
997 Furthermore, the recursor only works on Linux, Windows and Solaris (not
998 entirely). FreeBSD does not support the required functions. If you know
999 any important FreeBSD people, plea with them to support
1000 set/get/swapcontext! Alternatively, FreeBSD coders could read the solution
1001 presented here in figure 5.
1003 The 'Contributor of the Month' award goes to Mark Bergsma who has
1004 responded to our plea for help with the label compressor and contributed a
1005 wonderfully simple and right fix that allows PDNS to compress just as well
1006 as Other namerervers out there. An honorary mention goes to Ueli Heuer
1007 who, despite having no C++ experience, submitted an excellent SRV record
1010 Excellent work was also performed by Michel Stol, the Windows guy, in
1011 fixing all our non-portable stuff again. Christof Meerwald has also done
1012 wonderful work in porting MTasker to Windows, which was then used by
1013 Michel to get the recursor functioning on Windows.
1017 * dnspacket.cc was cleaned up by factoring out common operations
1019 * Heaps of work on the recursing nameserver. Has now achieved *days* of
1022 * Recursor renamed from syncres to pdns_recursor
1024 * PowerDNS can now serve records it does not know about. To benefit from
1025 this slightly undocumented feature, add 1024 to the numerical type of
1026 a record and include the record in binary form in your database. Used
1027 internally by the recursing nameserver but you can use it too.
1029 * PowerDNS now knows about SIG and KEY records *names*. It does not
1030 support them yet but can at least report so now.
1032 * HINFO records can now be transferred from a master to PowerDNS (thanks
1033 to Ueli Heuer for noticing it didn't work).
1035 * Yet more UltraSPARC alignment issues fixed (Chris Andrews).
1037 * Dropped non-lazy recursion, nobody was using it. Lazy recursion became
1038 even more lazy after Dan Bernstein pointed out that additional
1039 processing is not vital, so PowerDNS does its best to do additional
1040 processing on recursive queries, but does not scream murder if it does
1041 not succeed. Due to caching, the next identical query will be
1042 successfully additionally processed.
1044 * Label compression was improved so we can now fit all . records in 436
1045 bytes, this used to be 460! (Code & formal proof of correctness by
1048 * SRV support (incoming and outgoing), submitted by Ueli Heuer.
1050 * Generic backends do not support SOA serial autocalculation, it
1051 appears. Could lead to random SOA serials in case of a serial of 0 in
1052 the database. Fixed so that 0 stays zero in that case. Don't set the
1053 SOA serial to 0 when using Generic MySQL or Generic PostgreSQL!
1055 * J root-server address was updated to its new location.
1057 * SIGUSR1 now forces the recursor to print out statistics to the log.
1059 * Meaning of recursor logging was changed a bit - a cache hit is now a
1060 question that was answered with 0 outgoing packets needed. Used to be
1061 a weighted average of internal cache hits.
1063 * MySQL compilation did not include -lz which causes problems on some
1064 platforms. Thanks to James H. Cloos Jr for reporting this.
1066 * After a suggestion by Daniel Meyer and Florus Both, the built in
1067 webserver now reports the configuration name when multiple PowerDNS
1068 instances are active.
1070 * Brad Knowles noticed that zone2sql had problems with the root.zone,
1071 fixed. This also closes some other zone2sql annoyances with converting
1074 ----------------------------------------------------------------------
1076 1.3.12. Version 2.9.4
1078 Yet another grand release. Big news is the addition of a recursing
1079 nameserver which has sprung into existence over the past week. It is in
1080 use on several computers already but it is not ready for prime time.
1081 Complete integration with PowerDNS is expected around 2.9.5, for now the
1082 recursor is a separate program.
1084 In preliminary tests, the recursor appears to be four times faster than
1085 BIND 9 on a naive benchmark starting from a cold cache. BIND 9 managed to
1086 get through to some slower nameservers however, which were given up on by
1087 PowerDNS. We will continue to tune the recursor. See Chapter 12 for
1090 The BIND Backend has also been tested (see the bind-domain-status item
1091 below) rather heavily by several parties. After some discussion online,
1092 one of the BIND authors ventured that the newsgroup
1093 comp.protocols.dns.bind may now in fact be an appropriate venue for
1094 discussing PowerDNS. Since this discussion, traffic to the PowerDNS pages
1095 has increased sixfold and shows no signs of slowing down.
1097 From this, it is apparent that far more people are interested in PowerDNS
1098 than yet know about it. So spread the word!
1100 In other news, we now have a security page at Section 1.4. Furthermore,
1101 Maurice Nonnekes contributed an OpenBSD port! See his page for more
1104 New features and improvements:
1106 * All SQL queries in the generic backends are now available for
1107 configuration. (Martin Klebermass/bert hubert). See Section A.5.
1109 * A recursing nameserver! See Chapter 12.
1111 * An incoming AXFR now only starts a backend zone replacement
1112 transaction after the first record arrived successfully, thus making
1113 sure no work is done when a remote nameserver is unable/unwilling to
1116 * Zoneparser error messages were improved slightly (thanks to Stef van
1117 Dessel for spotting this shortcoming)
1119 * XS4ALL's Erik Bos checked how PowerDNS reacted to a BIND installation
1120 with almost 60.000 domains, some of which with >100.000 records, and
1121 he discovered the pdns_control bind-domain-status command became very
1122 slow with larger numbers of domains. Fixed, 60.000 domains are now
1123 listed in under one second.
1125 * If a remote nameserver disconnects during an incoming AXFR, the update
1126 is now rolled back, unless the AXFR was properly terminated.
1128 * The migration chapter mentioned the use of deprecated backends.
1130 A tremendous number of bugs were discovered and fixed:
1132 * Zone parser would only accept $include and not $INCLUDE
1134 * Zone parser had problems with $lines with comments on the end
1136 * Wildcard ANY queries were broken (thanks Colemarcus for spotting this)
1138 * A connection failure with the Generic backends would lead to a
1139 powerdns reload (cast of many)
1141 * Generic backends had some semantic problems with slave support.
1142 Symptoms were oft-repeated notifications and transfers (thanks to Mark
1143 Bergsma for helping resolve this).
1145 * Solaris version compiles again. Thanks to Mohamed Lrhazi for reporting
1148 * Some UltraSPARC alignment fixes. Thanks to Mohamed Lrhazi for being
1149 helpful in spotting these. One problem is still outstanding, Mohamed
1150 sent a core dump that tells us where the problem is. Expect the fix to
1151 be in 2.9.5. Volunteers can grep the source for 'UltraSPARC' to find
1152 where the problem is.
1154 * Our support of IPv6 on FreeBSD had phase of moon dependent bugs, fixed
1157 * Some crashes of and by pdns_control were fixed, thanks to Mark Bergsma
1158 for helping resolve these.
1160 * Outgoing AXFR in pdns installations with multiple loaded backends was
1161 broken (thanks to Stuart Walsh for reporting this).
1163 * A failed BIND Backend incoming AXFR would block the zone until it
1166 * Generic PostgreSQL backend wouldn't compile with newer libpq++, fixed
1167 by Julien Lemoine/SpeedBlue.
1169 * Potential bug (not observed) when listening on multiple interfaces
1172 * Some typos in manpages fixed (reported by Marco Davids).
1174 ----------------------------------------------------------------------
1176 1.3.13. Version 2.9.3a
1178 Note 2.9.3a is identical to 2.9.3 except that zone2sql does work
1180 Broad range of huge improvements. We now have an all-static .rpm and .deb
1181 for Linux users and a a link to an OpenBSD port. Major news is that work
1182 on the Bind backend has progressed to the point that we've just retired
1183 our last Bind server and replaced it with PowerDNS in Bind mode! This
1184 server is operating a number of master and slave setups so it should
1185 stress the Bind backend somewhat.
1187 This version is rapidly approaching the point where it is a
1188 better-Bind-than-Bind and nearly a drop-in replacement for authoritative
1189 setups. PowerDNS is now equipped with a powerful master/slave apparatus
1190 that offers a lot of insight and control to the user, even when operating
1191 from Bind zonefiles and a Bind configuration. Observe.
1193 After the SOA of ds9a.nl was raised:
1195 pdns[17495]: All slave domains are fresh
1196 pdns[17495]: 1 domain for which we are master needs notifications
1197 pdns[17495]: Queued notification of domain 'ds9a.nl' to 195.193.163.3
1198 pdns[17495]: Queued notification of domain 'ds9a.nl' to 213.156.2.1
1199 pdns[17520]: AXFR of domain 'ds9a.nl' initiated by 195.193.163.3
1200 pdns[17520]: AXFR of domain 'ds9a.nl' to 195.193.163.3 finished
1201 pdns[17521]: AXFR of domain 'ds9a.nl' initiated by 213.156.2.1
1202 pdns[17521]: AXFR of domain 'ds9a.nl' to 213.156.2.1 finished
1203 pdns[17495]: Removed from notification list: 'ds9a.nl' to 195.193.163.3 (was acknowledged)
1204 pdns[17495]: Removed from notification list: 'ds9a.nl' to 213.156.2.1 (was acknowledged)
1205 pdns[17495]: No master domains need notifications
1208 If however our slaves would ignore us, as some are prone to do, we can
1209 send some additional notifications:
1211 $ sudo pdns_control notify ds9a.nl
1213 pdns[17492]: Notification request for domain 'ds9a.nl' received
1214 pdns[17492]: Queued notification of domain 'ds9a.nl' to 195.193.163.3
1215 pdns[17492]: Queued notification of domain 'ds9a.nl' to 213.156.2.1
1216 pdns[17495]: Removed from notification list: 'ds9a.nl' to 195.193.163.3 (was acknowledged)
1217 pdns[17495]: Removed from notification list: 'ds9a.nl' to 213.156.2.1 (was acknowledged)
1220 Conversely, if PowerDNS needs to be reminded to retrieve a zone from a
1221 master, a command is provided:
1223 $ sudo pdns_control retrieve forfun.net
1224 Added retrieval request for 'forfun.net' from master 212.187.98.67
1225 pdns[17495]: AXFR started for 'forfun.net', transaction started
1226 pdns[17495]: Zone 'forfun.net' (/var/cache/bind/forfun.net) reloaded
1227 pdns[17495]: AXFR done for 'forfun.net', zone committed
1230 Also, you can force PowerDNS to reload a zone from disk immediately with
1231 pdns_control bind-reload-now. All this happens 'live', per your
1232 instructions. Without instructions, the right things also happen, but the
1233 operator is in charge.
1235 For more about all this coolness, see Section B.1.1 and Section A.9.2.
1237 Warning Again some changes in compilation instructions. The hybrid pgmysql
1238 backend has been split up into 'gmysql' and 'gpgsql', sharing a
1239 common base within the PowerDNS server itself. This means that you
1240 can no longer compile --with-modules="pgmysql" --enable-mysql
1241 --enable-pgsql but that you should now use: --with-modules="gmysql
1242 gpgsql". The old launch-names remain available.
1244 If you launch the Generic PgSQL backend as gpgsql2, all parameters
1245 will have gpsql2 as a prefix, for example pgsql2-dbname. If
1246 launched as gpsql, the regular names are in effect.
1248 Warning The pdns_control protocol was changed which means that older
1249 pdns_controls cannot talk to 2.9.3. The other way around is broken
1250 too. This may lead to problems with automatic upgrade scripts, so
1251 pay attention if your daemon is truly restarted.
1253 Also make sure no old pdns_control command is around to confuse
1258 * Bind backend can now deal with missing files and try to find them
1261 * Bind backend is now explicitly master capable and triggers the sending
1264 * General robustness improvements in Bind backend - many errors are now
1267 * Accessability, Serviceability. New pdns_server commands like
1268 bind-list-rejects (lists zones that could not be loaded, and the
1269 reason why), bind-reload-now (reload a zone from disk NOW), rediscover
1270 (reread named.conf NOW). More is coming up.
1272 * Added support for retrieving RP (Responsible Person) records from
1273 remote masters. Serving them was already possible.
1275 * Added support for LOC records, which encode the geographical location
1276 of a host, both serving and retrieving (thanks to Marco Davids using
1277 them on our last Bind server, forcing us to implement this silly
1280 * Configuration file parser now strips leading spaces too, allowing
1281 "chroot= /tmp" to work, as well as "chroot=/tmp" (Thanks to Hub Dohmen
1282 for reporting this for months on end).
1284 * Added bind-domain-status command that shows the status of all domains
1285 (when/if they were parsed, any errors encountered while parsing them).
1287 * Added bind-reload-now command that tries to reload a zone from disk
1288 NOW, and reports back errors to the operator immediatly.
1290 * Added retrieve command that queues a request to retrieve a zone from
1293 * Zones retrieved from masters are now stored way smaller on disk
1294 because the domain is stripped from records, which is derived from the
1295 configuration file. Retrieved zones are now prefixed with some
1296 information on where they came from.
1300 * gpgsql and gmysql backends split out of the hybrid pgmysqlbackend.
1301 This again changed compilation instructions!
1303 * pdns_control now uses the rarely seen SOCK_STREAM Unix Domain socket
1304 variety so it can transport large amounts of text, which is needed for
1305 the bind-domain-status command, for which see Section A.9.2. This
1306 breaks compatability with older pdns_control and pdns_server binaries!
1308 * Bind backend now ignores 'hint' and 'forward' and other unsupported
1311 * AXFRs are now logged more heavily by default. An AXFR is a heavy
1312 operation anyhow, some more logging does not further increase the load
1313 materially. Does help in clearing up what slaves are doing.
1315 * A lot of master/slave chatter has been silenced, making output more
1316 relevant. No more repetitive 'No master domains need notifications'
1317 etc, only changes are reported now.
1321 * Windows version did not compile without minor changes.
1323 * Confusing error reporting on Windows 98 (which does not support
1326 * Potential crashes with shortened packets addressed. An upgrade is
1329 * notify (which was already there, just badly documented) no longer
1330 prints out debugging garbage.
1332 * pgmysql backend had problems launching when not compiled in but
1333 available as a module. Workaround for 2.9.2 is 'load-modules=pgmysql',
1334 but even then gpgsql would not work! gmysql would then, however. These
1335 modules are now split out, removing such issues.
1337 ----------------------------------------------------------------------
1339 1.3.14. Version 2.9.2
1341 Bugfixes galore. Solaris porting created some issues on all platforms.
1342 Great news is that PowerDNS is now in Debian 'sid' (unstable). The 2.9.1
1343 packages in there currently aren't very good but the 2.9.2 ones will be.
1344 Many thanks to Wichert Akkerman, our 'downstream' for making this
1347 Warning The Generic MySQL backend, part of the Generic MySQL & PostgreSQL
1348 backend, is now the DEFAULT! The previous default, the 'mysql'
1349 backend (note the lack of 'g') is now DEPRECATED. This was the
1350 source of much confusion. The 'mysql' backend does not support
1351 MASTER or SLAVE operation. The Generic backends do.
1353 To get back the mysql backend, add --with-modules="mysql" or
1354 --with-dynmodules="mysql" if you prefer to load your modules at
1359 * Silly debugging output removed from the webserver (found by Paul
1362 * SEVERE: due to Solaris portability fixes, qtypes<127 were broken.
1363 These include NAPTR, ANY and AXFR. The upshot is that powerdns wasn't
1364 performing outgoing AXFRs nor ANY queries. These were the 'question
1365 for type -1' warnings in the log
1367 * incoming AXFR could theoretically miss some trailing records (not
1368 observed, but could happen)
1370 * incoming AXFR did not support TXT records (spotted by Paul Wouters)
1372 * with some remotes, an incoming AXFR would not terminate until a
1373 timeout occured (observed by Paul Wouters)
1375 * Documentation bug, pgmysql != mypgsql
1379 * Documented the 'random backend', see Section A.3.
1381 * Wichert Akkerman contributed three manpages.
1383 * Building PowerDNS on Unix is now documented somewhat more, see Section
1388 * pdns init.d script is now +x by default
1390 * OpenBSD is on its way of becoming a supported platform! As of 2.9.2,
1391 PowerDNS compiles on OpenBSD but swiftly crashes. Help is welcome.
1393 * ODBC backend (for Windows only) was missing from the distribution, now
1396 * xdb backend added - see Section A.11. Designed for use by root-server
1399 * Dynamic modules are back which is good news for distributors who want
1400 to make a pdns packages that does not depend one every database under
1403 ----------------------------------------------------------------------
1405 1.3.15. Version 2.9.1
1407 Thanks to the great enthusiasm from around the world, powerdns is now
1408 available for Solaris and FreeBSD users again! Furthermore, the Windows
1409 build is back. We are very grateful for the help of:
1431 We are happy to have been able to work with the open source community to
1436 * The monitor command set no longer allows the changing of non-existant
1439 * IBM Universal Database DB2 backend now included in source distribution
1442 * Oracle backend now included in source distribution (sligthly tested!)
1444 * configure script now searches for postgresql and mysql includes
1446 * Bind parser now no longer dies on records with a ' in them (Erik Bos)
1448 * The pipebackend was accidentally left out of 2.9
1450 * FreeBSD fixes (with help from Erik Bos, Alex Bleeker, Niels Bakker)
1452 * Heap of Solaris work (with help from Edvard Tuinder, Stefan Van Steen,
1453 Koos van den Hout, Roel van der Made and especially Mark Bakker). Now
1454 compiles in 2.7 and 2.8, haven't tried 2.9. May be a bit dysfunctional
1455 on 2.7 though - it won't do IPv6 and it won't serve AAAA. Patches
1458 * Windows 32 build is back! Michel Stol updated his earlier work to the
1461 * S/Linux (Linux on Sparc) build works now (with help from steven
1464 * Silly debugging message ('sd.ttl from cache') removed
1466 * .debs are back, hopefully in 'sid' soon! (Wichert Akkerman)
1468 * Removal of bzero and other less portable constructs. Discovered that
1469 recent Linux glibc's need -D_GNU_SOURCE (Wichert Akkerman).
1471 ----------------------------------------------------------------------
1475 Open source release. Do not deploy unless you know what you are doing.
1476 Stability is expected to return with 2.9.1, as are the binary builds.
1478 * License changed to the GNU General Public License version 2.
1480 * Cleanups by Erik Bos @ xs4all.
1482 * Build improvements by Wichert Akkerman
1484 * Lots of work on the build system, entirely revamped. By PowerDNS.
1486 ----------------------------------------------------------------------
1490 From this release onwards, we'll concentrate on stabilising for the 3.0
1491 release. So if you have any must-have features, let us know soonest. The
1492 2.8 release fixes a bunch of small stability issues and add two new
1493 features. In the spirit of the move to stability, this release has already
1494 been running 24 hours on our servers before release.
1496 * pipe backend gains the ability to restricts its invocation to a
1497 limited number of requests. This allows a very busy nameserver to
1498 still serve packets from a slow perl backend.
1500 * pipe backend now honors query-logging, which also documents which
1501 queries were blocked by the regex.
1503 * pipe backend now has its own backend chapter.
1505 * An incoming AXFR timeout at the wrong moment had the ability to crash
1506 the binary, forcing a reload. Thanks to our bug spotting champions
1507 Mike Benoit and Simon Kirby of NetNation for reporting this.
1509 ----------------------------------------------------------------------
1511 1.3.18. Version 2.7 and 2.7.1
1513 This version fixes some very long standing issues and adds a few new
1514 features. If you are still running 2.6, upgrade yesterday. If you were
1515 running 2.6.1, an upgrade is still strongly advised.
1519 * The controlsocket is now readable and writable by the 'setgid' user.
1520 This allows for non-root access to PDNS which is nice for mrtg or
1523 * MySQL backend (the non-generic one) gains the ability to read from a
1524 different table using the mysql-table setting.
1526 * pipe backend now has a configurable timeout using the pipe-timeout
1527 setting. Thanks fo Steve Bromwich for pointing out the need for this.
1529 * Experimental backtraces. If PowerDNS crashes, it will log a lot of
1530 numbers and sometimes more to the syslog. If you see these, please
1531 report them to us. Only available under Linux.
1535 * 2.7 briefly broke the mysql backend, so don't use it if you use that.
1538 * SOA records could sometimes have the wrong TTL. Thanks to Jonas
1539 Daugaard for reporting this.
1541 * An ANY query might lead to duplicate SOA records being returned under
1542 exceptional circumstances. Thanks to Jonas Daugaard for reporting
1545 * Underlying the above bug, packet compression could sometimes suddenly
1546 be turned off, leading to overly large responses and non-removal of
1549 * The allow-axfr-ips setting did not accept IP ranges (1.2.3.0/24) which
1550 the documentation claimed it did (thanks to Florus Both of Ascio
1551 technologies for being sufficiently persistent in reporting this).
1553 * Killed backends were not being respawned, leading to suboptimal
1554 behaviour on intermittent database errors. Thanks to Steve Bromwich
1557 * Corrupt packets during an incoming AXFR when acting as a slave would
1558 cause a PowerDNS reload instead of just failing that AXFR. Thanks to
1559 Mike Benoit and Simon Kirby of NetNation for reporting this.
1561 * Label compression in incoming AXFR had problems with large offsets,
1562 causing the above mentioned errors. Thanks to Mike Benoit and Simon
1563 Kirby of NetNation for reporting this.
1565 ----------------------------------------------------------------------
1567 1.3.19. Version 2.6.1
1569 Quick fix release for a big cache problem.
1571 ----------------------------------------------------------------------
1575 Performance release. A lot of work has been done to raise PDNS performance
1576 to staggering levels in order to take part in benchmarketing efforts.
1577 Together with our as yet unnamed partner, PDNS has been benchmarked at
1578 60.000 mostly cached queries/second on off the shelf PC hardware. Uncached
1579 performance was 17.000 uncached DNS queries/second on the .ORG domain.
1581 Performance has been increased by both making PDNS itself quicker but also
1582 by lowering the number of backend queries typically needed. Operators will
1583 typically see PDNS taking less CPU and the backend seeing less load.
1585 Furthermore, some real bugs were fixed. A couple of undocumented
1586 performance switches may appear in --help output but you are advised to
1587 stay away from these.
1589 Developers: this version needs the pdns-2.5.1 development kit, available
1590 on http://downloads.powerdns.com/releases/dev. See also Appendix C.
1594 * A big error in latency calculations - cached packets were weighed 50
1595 times less, leading to inflated latency reporting. Latency
1596 calculations are now correct and way lower - often in the microseconds
1599 * It is now possible to run with 0 second cache TTLs. This used to cause
1600 very frequent cache cleanups, leading to performance degradation.
1602 * Many tiny performance improvements, removing duplicate cache key
1603 calculations, etc. The cache itself has also been reworked to be more
1606 * First 'CNAME' backend query replaced by an 'ANY' query, which most of
1607 the time returns the actual record, preventing the need for a separate
1608 CNAME lookup, halving query load.
1610 * Much of the same for same-level-NS records on queries needing
1615 * Incidentally, the cache count would show 'unknown' packets, which was
1616 harmless but confusing. Thanks to Mike and Simon of NetNation for
1619 * SOA hostmaster with a . in the local-part would be cached wrongly,
1620 leading to a stray backslash in case of multiple successively SOA
1621 queries. Thanks to Ascio Techologies for spotting this bug.
1623 * zone2sql did not parse Verisign zonefiles correctly as these contained
1624 a $TTL statement in mid-record.
1626 * Sometimes packets would not be accounted, leading to 'udp-queries' and
1627 'udp-answers' divergence.
1631 * 'cricket' command added to init.d scripts that provides unadorned
1632 output for parsing by 'Cricket'.
1634 ----------------------------------------------------------------------
1636 1.3.21. Version 2.5.1
1638 Brown paper bag release fixing a huge memory leak in the new Query Cache.
1640 Developers: this version needs the new pdns-2.5.1 development kit,
1641 available on http://downloads.powerdns.com/releases/dev. See also Appendix
1644 And some small changes:
1646 * Added support for RFC2038 compliant negative-answer caching. This
1647 allows remotes to cache the fact that a domain does not exist and will
1648 not exist for a while. Thanks to Chris Thompson for pointing out how
1649 tiny our minds are. This feature may cause a noticeable reduction in
1652 * Small speedup to non-packet-cached queries, incidentally fixing the
1655 * pdns_control ccounts command outputs statistics on what is in the
1656 cache, which is useful to help optimize your caching strategy.
1658 ----------------------------------------------------------------------
1662 An important release which has seen quite a lot of trial and error
1663 testing. As a result, PDNS can now run with a huge cache and concurrent
1664 invalidations. This is useful when running of a slower database or under
1665 high traffic load with a fast database.
1667 Furthermore, the gpgsql2 backend has been validated for use and will soon
1668 supplant the gpgsql backend entirely. This also bodes well for the gmysql
1669 backend which is the same code.
1671 Also, a large amount of issues biting large scale slave operators were
1672 addressed. Most of these issues would only show up after prolonged uptime.
1676 * Query cache. The old Packet Cache only cached entire questions and
1677 their answers. This is very CPU efficient but does not lead to maximum
1678 hitrate. Two packets both needing to resolve smtp.you.com internally
1679 would not benefit from any caching. Furthermore, many different DNS
1680 queries lead to the same backend queries, like 'SOA for .COM?'.
1682 PDNS now also caches backend queries, but only those having no answer
1683 (the majority) and those having one answer (almost the rest).
1685 In tests, these additional caches appear to halve the database backend
1686 load numerically and perhaps even more in terms of CPU load. Often,
1687 queries with no answer are more expensive than those having one.
1689 The default ttls for the query-cache and negquery-cache are set to
1690 safe values (20 and 60 seconds respectively), you should be seeing an
1691 improvement in behaviour without sacrificing a lot in terms of quick
1694 The webserver also displays the efficiency of the new Query Cache.
1696 The old Packet Cache is still there (and useful) but see Chapter 9 for
1699 * There is now the ability to shut off some logging at a very early
1700 stage. High performance sites doing thousands of queries/second may in
1701 fact spend most of their CPU time on attempting to write out logging,
1702 even though it is ignored by syslog. The new flag log-dns-details, on
1703 by default, allows the operator to kill most informative-only logging
1704 before it takes any cpu.
1706 * Flags which can be switched 'on' and 'off' can now also be set to
1707 'off' instead of only to 'no' to turn them off.
1711 * Packet Cache is now case insensitive, leading to a higher hitrate
1712 because identical queries only differing in case now both match. Care
1713 is taken to restore the proper case in the answer sent out.
1715 * Packet Cache stores packets more efficiently now, savings are
1718 * The Packet Cache is now asynchronous which means that PDNS continues
1719 to answer questions while the cache is busy being purged or queried.
1720 Incidentally this will mean a cache miss where previously the question
1721 would wait until the cache became available again.
1723 The upshot of this is that operators can call pdns_control purge as
1724 often as desired without fearing performance loss. Especially the
1725 full, non-specific, purge was speeded up tremendously.
1727 This optimization is of little merit for small sites but is very
1728 important when running with a large packetcache, such as when using
1729 recursion under high load.
1731 * AXFR log messages now all contain the word 'AXFR' to ease grepping.
1733 * Linux static version now compiled with gcc 3.2 which is known to
1734 output better and faster code than the previously used 3.0.4.
1738 * Packetcache would sometimes send packets back with slightly modified
1739 flags if these differed from the flags of the cached copy.
1741 * Resolver code did bad things with filedescriptors leading to fd
1742 exhaustion after prolonged uptimes and many slave SOA currency checks.
1744 * Resolver code failed to properly log some errors, leading to operator
1745 uncertainty regarding to AXFR problems with remote masters.
1747 * After prolonged uptime, slave code would try to use privileged ports
1748 for originating queries, leading to bad replication efficiency.
1750 * Masters sending back answers in differing case from questions would
1751 lead to bogus 'Master tried to sneak in out-of-zone data' errors and
1754 ----------------------------------------------------------------------
1758 Developers: this version is compatible with the pdns-2.1 development kit,
1759 available on http://downloads.powerdns.com/releases/dev. See also Appendix
1762 This version fixes some stability issues with malformed or malcrafted
1763 packets. An upgrade is advised. Furthermore, there are interesting new
1768 * Recursive queries are now also cached, but in a separate namespace so
1769 non-recursive queries don't get recursed answers and vice versa. This
1770 should mean way lower database load for sites running with the current
1771 default lazy-recursion. Up to now, each and every recursive query
1772 would lead to a large amount of SQL queries.
1774 To prevent the packetcache from becoming huge, a separate
1775 recursive-cache-ttl can be specified.
1777 * The ability to change parameters at runtime was added. Currently, only
1778 the new query-logging flag can be changed.
1780 * Added query-logging flag which hints a backend that it should output a
1781 textual representation of queries it receives. Currently only gmysql
1782 and gpgsql2 honor this flag.
1784 * Gmysql backend can now also talk to PgSQL, leading to less code.
1785 Currently, the old postgresql driver ('gpgsql') is still the default,
1786 the new driver is available as 'gpgsql2' and has the benefit that it
1787 does query logging. In the future, gpgsql2 will become the default
1790 * DNS recursing proxy is now more verbose in logging odd events which
1791 may be caused by buggy recursing backends.
1793 * Webserver now displays peak queries/second 1 minute average.
1797 * Failure to connect to database in master/slave communicator thread
1798 could lead to an unclean reload, fixed.
1800 Documentation: added details for strict-rfc-axfrs. This feature can be
1801 used if very old clients need to be able to do zone transfers with PDNS.
1804 ----------------------------------------------------------------------
1808 Developers: this version is compatible with the pdns-2.1 development kit,
1809 available on http://downloads.powerdns.com/releases/dev. See also Appendix
1812 This release adds the Generic MySQL backend which allows full master/slave
1813 semantics with MySQL and InnoDB tables (or other tables that support
1814 transactions). See Section A.5.
1818 * Improved error messages in master/slave communicator will help down
1821 * slave-cycle-interval setting added. Very large sites with thousands of
1822 slave domains may need to raise this value above the default of 60.
1823 Every cycle, domains in undeterminate state are checked for their
1824 condition. Depending on the health of the masters, this may entail
1825 many SOA queries or attempted AXFRs.
1829 * 'pdns_control purge domain' and 'pdns_control purge domain$' were
1830 broken in version 2.2 and did not in fact purge the cache. There is a
1831 slight risk that domain-specific purge commands could force a reload
1832 in previous version. Thanks to Mike Benoit of NetNation for
1835 * Master/slave communicator thread got confused in case of delayed
1836 answers from slow masters. While not causing harm, this caused
1837 inefficient behaviour when testing large amounts of slave domains
1838 because additional 'cycles' had to pass before all domains would have
1839 their status ascertained.
1841 * Backends implementing special SOA semantics (currently only the
1842 undocumented 'pdns express backend', or homegrown backends) would
1843 under some circumstances not answer the SOA record in case of an ANY
1844 query. This should put an end to the last DENIC problems. Thanks to
1845 DENIC for helping us find the problem.
1847 ----------------------------------------------------------------------
1851 Developers: this version is compatible with the pdns-2.1 development kit,
1852 available on http://downloads.powerdns.com/releases/dev. See also Appendix
1855 Again a big release. PowerDNS is seeing some larger deployments in more
1856 demanding environments and these are helping shake out remaining issues,
1857 especially with recursing backends.
1859 The big news is that wildcard CNAMEs are now supported, an oft requested
1860 feature and nearly the only part in which PDNS differed from BIND in
1861 authoritative capabilities.
1863 If you were seeing signal 6 errors in PDNS causing reloads and
1864 intermittent service disruptions, please upgrade to this version.
1866 For operators of PowerDNS Express trying to host .DE domains, the very
1867 special soa-serial-offset feature has been added to placate the new DENIC
1868 requirement that the SOA serial be at least six digits. PowerDNS Express
1869 uses the SOA serial as an actual serial and not to insert dates and hence
1870 often has single digit soa serial numbers, causing big problems with .DE
1875 * Malformed or shortened TCP recursion queries would cause a signal 6
1876 and a reload. Same for EOF from the TCP recursing backend. Thanks to
1877 Simon Kirby and Mike Benoit of NetNation for helping debug this.
1879 * Timeouts on the TCP recursing backend were far too long, leading to
1880 possible exhaustion of TCP resolving threads.
1882 * pdns_control purge domain accidentally cleaned all packets with that
1883 name as a prefix. Thanks to Simon Kirby for spotting this.
1885 * Improved exception error logging - in some circumstances PDNS would
1886 not properly log the cause of an exception, which hampered problem
1891 * Wildcard CNAMEs now work as expected!
1893 * pdns_control purge can now also purge based on suffix, allowing
1894 operators to purge an entire domain from the packet cache instead of
1895 only specific records. See also Section B.1.1 Thanks to Mike Benoit
1896 for this suggestion.
1898 * soa-serial-offset for installations with small SOA serial numbers
1899 wishing to register .DE domains with DENIC which demands six-figure
1900 SOA serial numbers. See also Chapter 15.
1902 ----------------------------------------------------------------------
1906 This is a somewhat bigger release due to pressing demands from customers.
1907 An upgrade is advised for installations using Recursion. If you are using
1908 recursion, it is vital that you are aware of changes in semantics.
1909 Basically, local data will now override data in your recursing backend
1910 under most circumstances. Old behaviour can be restored by turning
1913 Developers: this version has a new pdns-2.1 development kit, available on
1914 http://downloads.powerdns.com/releases/dev. See also Appendix C.
1916 Warning Most users will run a static version of PDNS which has no
1917 dependencies on external libraries. However, some may need to run
1918 the dynamic version. This warning applies to these users.
1920 To run the dynamic version of PDNS, which is needed for backend
1921 drivers which are only available in source form, gcc 3.0 is
1922 required. RedHat 7.2 comes with gcc 3.0 as an optional component,
1923 RedHat 7.3 does not. However, the RedHat 7.2 Update gcc rpms
1924 install just fine on RedHat 7.3. For Debian, we suggest running
1925 'woody' and installing the g++-3.0 package. We expect to release a
1926 FreeBSD dynamic version shortly.
1930 * RPM releases sometimes overwrote previous configuration files. Thanks
1931 to Jorn Ekkelenkamp of Hubris/ISP Services for reporting this.
1933 * TCP recursion sent out overly large responses due to a byteorder
1934 mistake, confusing some clients. Thanks to the capable engineers of
1935 NetNation for bringing this to our attention.
1937 * TCP recursion in combination with a recursing backend on a
1938 non-standard port did not work, leading to a non-functioning TCP
1939 listener. Thanks to the capable engineers of NetNation for bringing
1940 this to our attention.
1942 Unexpected behaviour:
1944 * Wildcard URL records where not implemented because they are a
1945 performance penalty. To turn these on, enable wildcard-url in the
1948 * Unlike other nameservers, local data did not override the internet for
1949 recursing queries. This has mostly been brought into conformance with
1950 user expectations. If a recursive question can be answered entirely
1951 from local data, it is. To restore old behaviour, disable
1952 lazy-recursion. Also see Chapter 11.
1956 * Oracle support has been tuned, leading to the first public release of
1957 the Oracle backend. Zone2sql now outputs better SQL and the backend is
1958 now fully documented. Furthermore, the queries are compatible with the
1959 PowerDNS XML-RPC product, allowing PowerDNS express to run off Oracle.
1962 * Zone2sql now accepts --transactions to wrap zones in a transaction for
1963 PostgreSQL and Oracle output. This is a major speedup and also makes
1964 for better isolation of inserts. See Section 10.1.
1966 * pdns_control now has the ability to purge the PowerDNS cache or parts
1967 of it. This enables operators to raise the TTL of the Packet Cache to
1968 huge values and only to invalidate the cache when changes are made.
1969 See also Chapter 9 and Section B.1.1.
1971 ----------------------------------------------------------------------
1973 1.3.27. Version 2.0.1
1975 Maintenance release, fixing three small issues.
1977 Developers: this version is compatible with 1.99.11 backends.
1979 * PowerDNS ignored the logging-facility setting unless it was specified
1980 on the commandline. Thanks to Karl Obermayer from WebMachine
1981 Technologies for noticing this.
1983 * Zone2sql neglected to preserve 'slaveness' of domains when converting
1984 to the slave capable PostgreSQL backend. Thanks to Mike Benoit of
1985 NetNation for reporting this. Zone2sql now has a --slave option.
1987 * SOA Hostmaster addresses with dots in them before the @-sign were
1988 mis-encoded on the wire.
1990 ----------------------------------------------------------------------
1994 Two bugfixes, one stability/security related. No new features.
1996 Developers: this version is compatible with 1.99.11 backends.
2000 * zone2sql refused to work under some circumstances, taking 100% cpu and
2001 not functioning. Thanks to Andrew Clark and Mike Benoit for reporting
2004 * Fixed a stability issue where malformed packets could force PDNS to
2005 reload. Present in all earlier 2.0 versions.
2007 ----------------------------------------------------------------------
2009 1.3.29. Version 2.0 Release Candidate 2
2011 Mostly bugfixes, no really new features.
2013 Developers: this version is compatible with 1.99.11 backends.
2017 * chroot() works again - 2.0rc1 silently refused to chroot. Thanks to
2018 Hub Dohmen for noticing this.
2020 * setuid() and setgid() security features were silently not being
2021 performed in 2.0rc1. Thanks to Hub Dohmen for noticing this.
2023 * MX preferences over 255 now work as intended. Thanks to Jeff Crowe for
2026 * IPv6 clients can now also benefit from the recursing backend feature.
2027 Thanks to Andy Furnell for proving beyond any doubt that this did not
2030 * Extremely bogus code removed from DNS notification reception code -
2031 please test! Thanks to Jakub Jermar for working with us in figuring
2032 out just how broken this was.
2034 * AXFR code improved to handle more of the myriad different zonetransfer
2035 dialects available. Specifically, interoperability with Bind 4 was
2036 improved, as well as Bind 8 in 'strict rfc conformance' mode. Thanks
2037 again for Jakub Jermar for running many tests for us. If your
2038 transfers failed with 'Unknown type 14!!' or words to that effect,
2043 * Win32 version now has a zone2sql tool.
2045 * Win32 version now has support for specifying how urgent messages
2046 should be before they go to the NT event log.
2050 * One persistent report of the default 'chroot=./' configuration not
2053 * One report of disable-axfr and allow-axfr-ips not working as intended.
2055 * Support for relative paths in zones and in Bind configuration is not
2056 bug-for-bug compatible with bind yet.
2058 ----------------------------------------------------------------------
2060 1.3.30. Version 2.0 Release Candidate 1
2062 The MacOS X release! A very experimental OS X 10.2 build has been added.
2063 Furthermore, the Windows version is now in line with Unix with respect to
2064 capabilities. The ODBC backend now has the code to function as both a
2067 Developers: this version is compatible with 1.99.11 backends.
2069 * Implemented native packet response parsing code, allowing Windows to
2070 perform AXFR and NS and SOA queries.
2072 * This is the first version for which we have added support for Darwin
2073 6.0, which is part of the forthcoming Mac OS X 10.2. Please note that
2074 although this version is marked RC1, that we have not done extensive
2075 testing yet. Consider this a technology preview.
2077 * The Darwin version has been developed on Mac OS X 10.2 (6C35).
2078 Other versions may or may not work.
2080 * Currently only the random, bind, mysql and pdns backends are
2083 * The menu based installer script does not work, you will have to
2084 edit pathconfig by hand as outlined in chapter 2.
2086 * On Mac OS X Client, PDNS will fail to start because a system
2087 service is already bound to port 53.
2089 This version is distributed as a compressed tar file. You should
2090 follow the generic UNIX installation instructions.
2094 * Zone2sql PostgreSQL mode neglected to lowercase $ORIGIN. Thanks to
2095 Maikel Verheijen of Ladot for spotting this.
2097 * Zone2sql PostgreSQL mode neglected to remove a trailing dot from
2098 $ORIGIN if present. Thanks to Thanks to Maikel Verheijen of Ladot for
2101 * Zonefile parser was not compatible with bind when $INCLUDING
2102 non-absolute filenames. Thanks to Jeff Miller for working out how this
2105 * Bind configuration parser was not compatible with bind when including
2106 non-absolute filenames. Thanks to Jeff Miller for working out how this
2109 * Documentation incorrectly listed the Bind backend as 'slave capable'.
2110 This is not yet true, now labeled 'experimental'.
2112 Windows changes. We are indebted to Dimitry Andric who educated us in the
2113 ways of distributing Windows software.
2115 * pdns.conf is now read if available.
2117 * Console version responds to ^c now.
2119 * Default pdns.conf added to distribution
2121 * Uninstaller missed several files, leaving remnants behind
2123 * DLLs are now installed locally, with the pdns executable.
2125 * pdns_control is now also available on Windows
2127 * ODBC backend can now act as master and slave. Experimental.
2129 * The example zone missed indexes and had other faults.
2131 * A runtime DLL that is present on most windows systems (but not all!)
2134 ----------------------------------------------------------------------
2136 1.3.31. Version 1.99.12 Prerelease
2138 The Windows release! See Chapter 3. Beware, windows support is still very
2139 fresh and untested. Feedback is very welcome.
2141 Developers: this version is compatible with 1.99.11 backends.
2143 * Windows 2000 codebase merge completed. This resulted in quite some
2144 changes on the Unix end of things, so this may impact reliability
2146 * ODBC backend added for Windows. See Section A.10.
2148 * IBM DB2 Universal Database backend available for Linux. See Section
2151 * Zone2sql now understands $INCLUDE. Thanks to Amaze Internet for
2154 * The SOA Mininum TTL now has a configurable default
2155 (soa-minimum-ttl)value to placate the DENIC requirements.
2157 * Added a limit on the simultaneous numbers of TCP connections to accept
2158 (max-tcp-connections). Defaults to 10.
2162 * When operating in virtual hosting mode (See Chapter 8), the additional
2163 init.d scripts would not function correctly and interface with other
2166 * PDNS neglected to conserve case on answers. So a query for
2167 WwW.PoWeRdNs.CoM would get an answer listing the address of
2168 www.powerdns.com. While this did not confuse resolvers, it is better
2169 to conserve case. This has semantical concequences for all backends,
2170 which the documentation now spells out.
2172 * PostgreSQL backend was case sensitive and returned only answers in
2173 case an exact match was found. The Generic PostgreSQL backend is now
2174 officially all lower case and zone2sql in PostgreSQL mode enforces
2175 this. Documentation has been been updated to reflect the case change.
2176 Thanks to Maikel Verheijen of Ladot for spotting this!
2178 * Documentation bug - postgresql create/index statements created a
2179 duplicate index. If you've previously copy pasted the commands and not
2180 noticed the error, execute CREATE INDEX rec_name_index ON
2181 records(name) to remedy. Thanks to Jeff Miller for reporting this.
2182 This also lead to depressingly slow 'ANY' lookups for those of you
2187 * pdns_control (see Section B.1.1) now opens the local end of its socket
2188 in /tmp instead of next to the remote socket (by default /var/run).
2189 This eases the way for allowing non-root access to pdns_control. When
2190 running chrooted (see Chapter 7), the local socket again moves back to
2193 * pdns_control now has a 'version' command. See Section B.1.1.
2195 ----------------------------------------------------------------------
2197 1.3.32. Version 1.99.11 Prerelease
2199 This release is important because it is the first release which is
2200 accompanied by an Open Source Backend Development Kit, allowing external
2201 developers to write backends for PDNS. Furthermore, a few bugs have been
2204 * Lines with only whitespace in zone files confused PDNS (thanks Henk
2207 * PDNS did not properly parse TTLs with symbolic sufixes in zone files,
2208 ie 2H instead of 7200 (thanks Henk Wevers)
2210 ----------------------------------------------------------------------
2212 1.3.33. Version 1.99.10 Prerelease
2214 IMPORTANT: there has been a tiny license change involving free public
2215 webbased dns hosting, check out the changes before deploying!
2217 PDNS is now feature complete, or very nearly so. Besides adding features,
2218 a lot of 'fleshing out' work is done now. There is an important
2219 performance bug fix which may have lead to disappointing benchmarks - so
2220 if you saw any of that, please try either this version or 1.99.8 which
2221 also does not have the bug.
2223 This version has been very stable for us on multiple hosts, as was 1.99.9.
2225 PostgreSQL users should be aware that while 1.99.10 works with the schema
2226 as presented in earlier versions, advanced features such as master or
2227 slave support will not work unless you create the new 'domains' table as
2232 * Wildcard AAAA queries sometimes received an NXDOMAIN error where they
2233 should have gotten an empty NO ERROR. Thanks to Jeroen Massar for
2234 spotting this on the .TK TLD!
2236 * Do not disable the packetcache for 'recursion desired' packets unless
2237 a recursor was configured. Thanks to Greg Schueler for noticing this.
2239 * A failing backend would not be reinstated. Thanks to 'Webspider' for
2240 discovering this problem with PostgreSQL connections that die after
2241 prolonged inactivity.
2243 * Fixed loads of IPv6 transport problems. Thanks to Marco Davids and
2244 others for testing. Considered ready for production now.
2246 * Zone2sql printed a debugging statement on range $GENERATE commands.
2247 Thanks to Rene van Valkenburg for spotting this.
2251 * PDNS can now act as a master, sending out notifications in case of
2252 changes and allowing slaves to AXFR. Big rewording of replication
2253 support, domains are now either 'native', 'master' or 'slave'. See
2254 Chapter 13 for lots of details.
2256 * Zone2sql in PostgreSQL mode now populates the 'domains' table for easy
2257 master, slave or native replication support.
2259 * Ability to disable those annoying Windows DNS Dynamic Update messages
2260 from appearing in the log. See log-failed-updates in Chapter 15.
2262 * Ability to run on IPv6 transport only
2264 * Logging can now happen under a 'facility' so all PDNS messages appear
2265 in their own file. See Section 6.3.
2267 * Different OS releases of PDNS now get different install path defaults.
2268 Thanks to Mark Lastdrager for nagging about this and to Nero Imhard
2269 and Frederique Rijsdijk for suggesting saner defaults.
2271 * Infrastructure for 'also-notify' statements added.
2273 ----------------------------------------------------------------------
2275 1.3.34. Version 1.99.9 Early Access Prerelease
2277 This is again a feature and an infrastructure release. We are nearly
2278 feature complete and will soon start work on the backends to make sure
2279 that they are all master, slave and 'superslave' capable.
2283 * PDNS sometimes sent out duplicate replies for packets passed to the
2284 recursing backend. Mostly a problem on SMP systems. Thanks to Mike
2285 Benoit for noticing this.
2287 * Out-of-bailiwick CNAMES (ie, a CNAME to a domain not in PDNS) caused a
2288 'ServFail' packet in 1.99.8, indicating failure, leading to hosts not
2289 resolving. Thanks to Martin Gillstrom for noticing this.
2291 * Zone2sql balked at zones editted under operating sytems terminating
2292 files with ^Z (Windows). Thanks Brian Willcott for reporting this.
2294 * PostgreSQL backend logged the password used to connect. Now only does
2295 so in case of failure to connect. Thanks to 'Webspider' for noticing
2298 * Debian unstable distribution wrongly depended on home compiled
2299 PostgreSQL libraries. Thanks to Konrad Wojas for noticing this.
2303 * When operating as a slave, AAAA records are now supported in the zone.
2304 They were already supported in master zones.
2306 * IPv6 transport support - PDNS can now listen on an IPv6 socket using
2307 the local-ipv6 setting.
2309 * Very silly randombackend added which appears in the documentation as a
2310 sample backend. See Appendix C.
2312 * When transferring a slave zone from a master, out of zone data is now
2313 rejected. Malicious operators might try to insert bad records
2316 * 'Supermaster' support for automatic provisioning from masters. See
2319 * Recursing backend can now live on a non-standard (!=53) port. See
2322 * Slave zone retrieval is now queued instead of immediate, which scales
2323 better and is more resilient to temporary failures.
2325 * max-queue-length parameter. If this many packets are queued for
2326 database attention, consider the situation hopeless and respawn.
2330 * SOA records are now 'special' and each backend can optionally generate
2331 them in special ways. PostgreSQL backend does so when operating as a
2334 * Writing backends is now a lot easier. See Appendix C.
2336 * Added Bindbackend to internal regression tests, confirming that it is
2339 ----------------------------------------------------------------------
2341 1.3.35. Version 1.99.8 Early Access Prerelease
2343 A lot of infrastructure work gearing up to 2.0. Some stability bugs fixed
2344 and a lot of new features.
2348 * Bindbackend was overly complex and crashed on some systems on startup.
2349 Simplified launch code.
2351 * SOA fields were not always properly filled in, causing default values
2352 to go out on the wire
2354 * Obscure bug triggered by malicious packets (we know who you are) in
2355 SOA finding code fixed.
2357 * Magic serial number calculation contained a double free leading to
2360 * Standards violation, questions for domains for which PDNS was
2361 unauthoritative now get a SERVFAIL answer. Thanks to the IETF
2362 Namedroppers list for helping out with this.
2364 * Slowly launching backends were being relaunched at a great rate when
2365 queries were coming in while launching backends.
2367 * MySQL-on-unix-domain-socket on SMP systems was overwhelmed by the
2368 quick connection rate on launch, inserted a small 50ms delay.
2370 * Some SMP problems appear to be compiler related. Shifted to GCC 3.0.4
2373 * Ran ispell on documentation.
2375 Feature enhancements:
2377 * Recursing backend. See Chapter 11. Allows recursive and authoritative
2378 DNS on the same IP address.
2380 * NAPTR support, which is especially useful for the ENUM/E.164
2383 * Zone transfers can now be allowed per netmask instead of only per IP
2386 * Preliminary support for slave operation included. Only for the
2387 adventurous right now! See Section 13.2
2389 * All record types now documented, see Chapter 17.
2391 ----------------------------------------------------------------------
2393 1.3.35.1. Known bugs
2395 Wildcard CNAMES do not work as they do with bind.
2397 Recursion sometimes sends out duplicate packets (fixed in 1.99.9
2400 Some stability issues which are caught by the guardian
2402 ----------------------------------------------------------------------
2404 1.3.35.2. Missing features
2406 Features present in this document, but disabled or withheld from the
2409 * gmysqlbackend, oraclebackend
2411 ----------------------------------------------------------------------
2413 1.3.36. Version 1.99.7 Early Access Prerelease
2415 Named.conf parsing got a lot of work and many more bind configurations can
2416 now be parsed. Furthermore, error reporting was improved. Stability is
2421 * Bind parser got confused by filenames with underscores and colons.
2423 * Bind parser got confused by spaces in quoted names
2425 * FreeBSD version now stops and starts when instructed to do so.
2427 * Wildcards were off by default, which violates standards. Now on by
2430 * --oracle was broken in zone2sql
2432 Feature enhancements:
2434 * Line number counting goes on as it should when including files in
2437 * Added --no-config to enable users to start the pdns daemon without
2438 parsing the configuration file.
2440 * zone2sql now has --bare for unformatted output which can be used to
2441 generate insert statements for different database layouts
2443 * zone2sql now has --gpgsql, which is an alias for --mysql, to output in
2444 a format useful for the default Generic PgSQL backend
2446 * zone2sql is now documented.
2448 ----------------------------------------------------------------------
2450 1.3.36.1. Known bugs
2452 Wildcard CNAMES do not work as they do with bind.
2454 ----------------------------------------------------------------------
2456 1.3.36.2. Missing features
2458 Features present in this document, but disabled or withheld from the
2461 * gmysqlbackend, oraclebackend
2463 Some of these features will be present in newer releases.
2465 ----------------------------------------------------------------------
2467 1.3.37. Version 1.99.6 Early Access Prerelease
2469 This version is now running on dns-eu1.powerdns.net and working very well
2470 for us. But please remain cautious before deploying!
2474 * Webserver neglected to show log messages
2476 * TCP question/answer miscounted multiple questions over one socket.
2477 Fixed misnaming of counter
2479 * Packetcache now detects clock skew and times out entries
2481 * named.conf parser now reports errors with line number and offending
2484 * Filenames in named.conf can now contain :
2486 Feature enhancements:
2488 * The webserver now by default does not print out configuration
2489 statements, which might contain database backends. Use
2490 webserver-print-arguments to restore the old behaviour.
2492 * Generic PostgreSQL backend is now included. Still rather beta.
2494 ----------------------------------------------------------------------
2496 1.3.37.1. Known bugs
2498 FreeBSD version does not stop when requested to do so.
2500 Wildcard CNAMES do not work as they do with bind.
2502 ----------------------------------------------------------------------
2504 1.3.37.2. Missing features
2506 \r Features present in this document, but disabled or withheld from the
2509 * gmysqlbackend, oraclebackend
2511 Some of these features will be present in newer releases.
2513 ----------------------------------------------------------------------
2515 1.3.38. Version 1.99.5 Early Access Prerelease
2517 The main focus of this release is stability and TCP improvements. This is
2518 the first release PowerDNS-the-company actually considers for running on
2519 its production servers!
2523 * Zone2sql received a floating point division by zero error on
2524 named.confs with less than 100 domains.
2526 * Huffman encoder failed without specific error on illegal characters in
2529 * Fixed huge memory leaks in TCP code.
2531 * Removed further file descriptor leaks in guardian respawning code
2533 * Pipebackend was too chatty.
2535 * pdns_server neglected to close fds 0, 1 & 2 when daemonizing
2537 Feature enhancements:
2539 * bindbackend can be instructed not to check the ctime of a zone by
2540 specifying bind-check-interval=0, which is also the new default.
2542 * pdns_server --list-modules lists all available modules.
2544 Performance enhancements:
2546 * TCP code now only creates a new database connection for AXFR.
2548 * TCP connections timeout rather quickly now, leading to less load on
2551 ----------------------------------------------------------------------
2553 1.3.38.1. Known bugs
2555 FreeBSD version does not stop when requested to do so.
2557 Wildcard CNAMES do not work as they do with bind.
2559 ----------------------------------------------------------------------
2561 1.3.38.2. Missing features
2563 \r Features present in this document, but disabled or withheld from the
2566 * gmysqlbackend, oraclebackend, gpgsqlbackend
2568 Some of these features will be present in newer releases.
2570 ----------------------------------------------------------------------
2572 1.3.39. Version 1.99.4 Early Access Prerelease
2574 A lot of new named.confs can now be parsed, zone2sql & bindbackend have
2575 gained features and stability.
2579 * Label compression was not always enabled, leading to large reply
2582 * Database errors on TCP server lead to a nameserver reload by the
2585 * MySQL backend neglected to close its connection properly.
2587 * BindParser miss parsed some IP addresses and netmasks.
2589 * Truncated answers were also truncated on the packetcache, leading to
2590 truncated TCP answers.
2592 Feature enhancements:
2594 * Zone2sql and the bindbackend now understand the Bind $GENERATE{}
2597 * Zone2sql can optionally gloss over non-existing zones with
2598 --on-error-resume-next.
2600 * Zone2sql and the bindbackend now properly expand @ also on the right
2601 hand side of records.
2603 * Zone2sql now sets a default TTL.
2605 * DNS UPDATEs and NOTIFYs are now logged properly and sent the right
2608 Performance enhancements:
2610 * 'Fancy records' are no longer queried for on ANY queries - this is a
2613 ----------------------------------------------------------------------
2615 1.3.39.1. Known bugs
2617 FreeBSD version does not stop when requested to do so.
2619 Zone2sql refuses named.confs with less than 100 domains.
2621 Wildcard CNAMES do not work as they do with bind.
2623 ----------------------------------------------------------------------
2625 1.3.39.2. Missing features
2627 \r Features present in this document, but disabled or withheld from the
2630 * gmysqlbackend, oraclebackend, gpgsqlbackend
2632 Some of these features will be present in newer releases.
2634 ----------------------------------------------------------------------
2636 1.3.40. Version 1.99.3 Early Access Prerelease
2638 The big news in this release is the BindBackend which is now capable of
2639 parsing many more named.conf Bind configurations. Furthermore, PDNS has
2640 successfully parsed very large named.confs with large numbers of small
2641 domains, as well as small numbers of large domains (TLD).
2643 Zone transfers are now also much improved.
2647 * zone2sql leaked file descriptors on each domain, used wrong Bison
2648 recursion leading to parser stack overflows. This limited the amount
2649 of domains that could be parsed to 1024.
2651 * zone2sql can now read all known zonefiles, with the exception of those
2652 containing $GENERATE
2654 * Guardian relaunching a child lost two file descriptors
2656 * Don't die on a connection reset by peer during zone transfer.
2658 * Webserver does not crash anymore on ringbuffer resize
2660 Feature enhancements:
2662 * AXFR can now be disabled, and re-enabled per IP address
2664 * --help accepts a parameter, will then show only help items with that
2667 * zone2sql now accepts a --zone-name parameter
2669 * BindBackend maturing - 9500 zones parsed in 3.5 seconds. No longer
2672 Performance enhancements:
2674 * Implemented RFC-breaking AXFR format (which is the industry standard).
2675 Zone transfers now zoom along at wirespeed (many megabits/s).
2677 ----------------------------------------------------------------------
2679 1.3.40.1. Known bugs
2681 FreeBSD version does not stop when requested to do so.
2683 BindBackend cannot parse zones with $GENERATE statements.
2685 ----------------------------------------------------------------------
2687 1.3.40.2. Missing features
2689 \r Features present in this document, but disabled or withheld from the
2692 * gmysqlbackend, oraclebackend, gpgsqlbackend
2694 Some of these features will be present in newer releases.
2696 ----------------------------------------------------------------------
2698 1.3.41. Version 1.99.2 Early Access Prerelease
2702 * Database backend reload does not hang the daemon anymore
2704 * Buffer overrun in local socket address initialisation may have caused
2707 * setuid changed the uid to the gid of the selected user
2709 * zone2sql doesn't coredump on invocation anymore. Fixed lots of small
2712 * Don't parse configuration file when creating configuration file. This
2713 was a problem with reinstalling.
2715 Performance improvements:
2717 * removed a lot of unnecessary gettimeofday calls
2719 * removed needless select(2) call in case of listening on only one
2722 * removed 3 useless syscalls in the fast path
2724 Having said that, more work may need to be done. Testing on a 486 saw
2725 packet rates in a simple setup (question/wait/answer/question..) improve
2726 from 200 queries/second to over 400.
2728 Usability improvements:
2730 * Fixed error checking in init.d script (show, mrtg)
2732 * Added 'uptime' to the mrtg output
2734 * removed further GNUisms from installer and init.d scripts for use on
2737 * Debian package and apt repository, thanks to Wichert Akkerman.
2739 * FreeBSD /usr/ports, thanks to Peter van Dijk (in progress).
2741 Stability may be an issue as well as performance. This version has a
2742 tendency to log a bit too much which slows the nameserver down a lot.
2744 ----------------------------------------------------------------------
2746 1.3.41.1. Known bugs
2748 Decreasing a ringbuffer on the website is a sure way to crash the daemon.
2749 Zone2sql, while improved, still has problems with a zone in the following
2756 To fix, add 'name' to the second line.
2758 Zone2sql does not close filedescriptors.
2762 FreeBSD version does not stop when requested via the init.d script.
2766 ----------------------------------------------------------------------
2768 1.3.41.2. Missing features
2770 Features present in this document, but disabled or withheld from the
2773 * gmysqlbackend, oraclebackend, gpgsqlbackend
2775 * fully functioning bindbackend - will try to parse named.conf, but
2778 Some of these features will be present in newer releases.
2780 ----------------------------------------------------------------------
2782 1.3.42. Version 1.99.1 Early Access Prerelease
2784 This is the first public release of what is going to become PDNS 2.0. As
2785 such, it is not of production quality. Even PowerDNS-the-company does not
2788 Stability may be an issue as well as performance. This version has a
2789 tendency to log a bit too much which slows the nameserver down a lot.
2791 ----------------------------------------------------------------------
2793 1.3.42.1. Known bugs
2795 Decreasing a ringbuffer on the website is a sure way to crash the daemon.
2796 Zone2sql is very buggy.
2798 ----------------------------------------------------------------------
2800 1.3.42.2. Missing features
2802 Features present in this document, but disabled or withheld from the
2805 * gmysqlbackend, oraclebackend, gpgsqlbackend
2807 * fully functioning bindbackend - will not parse configuration files
2809 Some of these features will be present in newer releases.
2811 ----------------------------------------------------------------------
2815 As of the 8th of January 2003, no actual security problems with PowerDNS
2816 2.9.4 or later are known about. This page will be updated with all bugs
2817 which are deemed to be security problems, or could conceivably lead to
2818 those. Any such notifications will also be sent to all PowerDNS
2819 mailinglists and BUGTRAQ.
2821 All versions of PowerDNS before 2.9 are known to suffer from remote denial
2822 of service problems which can disrupt operation. Please upgrade to 2.9.4
2823 as this page will only contain detailed security information from 2.9.4
2826 If you have a security problem to report, please email us at both
2827 <powerdns@powerdns.com> and at <ahu@ds9a.nl>. We adhere to the Rain Forest
2828 Puppy Full Disclosure Policy (RFPolicy) v2.0 and we ask you to do the
2831 We remind PowerDNS users that under the terms of the GNU General Public
2832 License, PowerDNS comes with ABSOLUTELY NO WARRANTY. This license is
2833 included in the distribution and in this documentation, see Appendix E.
2835 ----------------------------------------------------------------------
2837 1.5. Acknowledgements
2839 PowerDNS is grateful for the help of the following people or institutions:
2847 * Mike Benoit (NetNation Communication Inc.)
2861 * IETF Namedroppers mailinglist
2865 (these people don't share the blame for any errors or mistakes in powerdns
2866 - those are all ours)
2868 ----------------------------------------------------------------------
2870 Chapter 2. Installing on Unix
2872 You will typically install PDNS > 2.9 via source or via a package. Earlier
2873 versions used a clumsy binary installer.
2875 ----------------------------------------------------------------------
2877 2.1. Possible problems at this point
2879 At this point some things may have gone wrong. Typical errors include:
2881 error while loading shared libraries: libstdc++.so.x: cannot open shared
2882 object file: No such file or directory
2884 Errors looking like this indicate a mismatch between your PDNS
2885 distribution and your Unix operating system. Download the static
2886 PDNS distribution for your operating system and try again. Please
2887 contact <pdns@powerdns.com> if this is impractical.
2889 ----------------------------------------------------------------------
2891 2.2. Testing your install
2893 After installing, it is a good idea to test the basic functionality of the
2894 software before configuring database backends. For this purpose, PowerDNS
2895 contains the 'bindbackend' which has a domain built in example.com, which
2896 is officially reserved for testing. To test, edit pdns.conf and add the
2897 following if not already present:
2903 This configures powerdns to 'launch' the bindbackend, and enable the
2904 example zones. To fire up PDNS in testing mode, execute: /etc/init.d/pdns
2905 monitor, where you may have to substitute the location of your SysV init.d
2906 location you specified earlier. In monitor mode, the pdns process runs in
2907 the foreground and is very verbose, which is perfect for testing your
2908 install. If everything went all right, you can query the example.com
2911 host www.example.com 127.0.0.1
2914 www.example.com should now have IP address 1.2.3.4. The host command can
2915 usually be found in the dnsutils package of your operating system.
2916 Alternate command is: dig www.example.com A @127.0.0.1 or even nslookup
2917 www.example.com 127.0.0.1, although nslookup is not advised for DNS
2920 * example.com SOA record
2922 * example.com NS record pointing to ns1.example.com
2924 * example.com NS record pointing to ns2.example.com
2926 * example.com MX record pointing to mail.example.com
2928 * example.com MX record pointing to mail1.example.com
2930 * mail.example.com A record pointing to 4.3.2.1
2932 * mail1.example.com A record pointing to 5.4.3.2
2934 * ns1.example.com A record pointing to 4.3.2.1
2936 * ns2.example.com A record pointing to 5.4.3.2
2938 * host-0 to host-9999.example.com A record pointing to 2.3.4.5
2940 When satisfied that basic functionality is there, type QUIT to exit the
2941 monitor mode. The adventurous may also type SHOW * to see some internal
2942 statistics. In case of problems, you will want to read the following
2945 ----------------------------------------------------------------------
2947 2.2.1. Typical errors
2949 At this point some things may have gone wrong. Typical errors include:
2951 binding to UDP socket: Address already in use
2953 This means that another nameserver is listening on port 53
2954 already. You can resolve this problem by determining if it is safe
2955 to shutdown the nameserver already present, and doing so. If
2956 uncertain, it is also possible to run PDNS on another port. To do
2957 so, add local-port=5300 to pdns.conf, and try again. This however
2958 implies that you can only test your nameserver as clients expect
2959 the nameserver to live on port 53.
2961 binding to UDP socket: Permission denied
2963 You must be superuser in order to be able to bind to port 53. If
2964 this is not a possibility, it is also possible to run PDNS on
2965 another port. To do so, add local-port=5300 to pdns.conf, and try
2966 again. This however implies that you can only test your nameserver
2967 as clients expect the nameserver to live on port 53.
2969 Unable to launch, no backends configured for querying
2971 PDNS did not find the launch=bind instruction in pdns.conf.
2973 Multiple IP addresses on your server, PDNS sending out answers on the
2974 wrong one, Massive amounts of 'recvfrom gave error, ignoring: Connection
2977 If you have multiple IP addresses on the internet on one machine,
2978 UNIX often sends out answers over another interface than which the
2979 packet came in on. In such cases, use local-address to bind to
2980 specific IP addresses, which can be comma separated. The second
2981 error comes from remotes disregarding answers to questions it
2982 didn't ask to that IP address and sending back ICMP errors.
2984 ----------------------------------------------------------------------
2986 2.3. Running PDNS on unix
2988 PDNS is normally controlled via a SysV-style init.d script, often located
2989 in /etc/init.d or /etc/rc.d/init.d. This script accepts the following
2994 Monitor is a special way to view the daemon. It executes PDNS in
2995 the foreground with a lot of logging turned on, which helps in
2996 determining startup problems. Besides running in the foreground,
2997 the raw PDNS control socket is made available. All external
2998 communication with the daemon is normally sent over this socket.
2999 While useful, the control console is not an officially supported
3000 feature. Commands which work are: QUIT, SHOW *, SHOW varname,
3005 Start PDNS in the background. Launches the daemon but makes no
3006 special effort to determine success, as making database
3007 connections may take a while. Use status to query success. You can
3008 safely run start many times, it will not start additional PDNS
3013 Restarts PDNS if it was running, starts it otherwise.
3017 Query PDNS for status. This can be used to figure out if a launch
3018 was successful. The status found is prefixed by the PID of the
3023 Requests that PDNS stop. Again, does not confirm success. Success
3024 can be ascertained with the status command.
3028 Dumps a lot of statistics of a running PDNS daemon. It is also
3029 possible to single out specific variable by using the show
3034 Show a single statistic, as present in the output of the dump.
3038 See the performance monitoring Chapter 6.
3040 ----------------------------------------------------------------------
3042 Chapter 3. Installing on Microsoft Windows
3044 Note PowerDNS support for Windows is, as of 1.99.12, very recent and
3045 therefore quite 'beta'. For reliability, we currently advise the use
3046 of the Unix versions. Furthermore there is no support for master or
3047 slave operation in the ODBC backend, which is the only one provided
3048 currently. This will be fixed soon.
3050 As of 1.99.12, PowerDNS supports Windows natively. PDNS can act as an NT
3051 service and works with any ODBC drivers you may have.
3053 To install PowerDNS for Windows you should check if your PC meets the
3054 following requirements:
3056 * A PC running Microsoft NT (with a recent servicepack and at least mdac
3059 * An ODBC source containing valid zone information (an example MS Access
3060 database is supplied in the form of powerdns.mdb).
3062 If your system meets these requirements, download the installer from
3063 http://www.powerdns.com/pdns/. After downloading the file begin the
3064 installation procedure by starting powerdns-VERSION.exe.
3066 After installing the software you should create a valid ODBC source. To do
3067 this you have open the ODBC sources dialog: Start->Settings->Control
3068 Panel->Administrative Tools->Data Sources (ODBC).
3070 We'll use the example zone database that is included in the installation
3071 to explain how to create a source.
3073 \r When you are in the ODBC sources dialog you activate the System DSN tab.
3075 Note It is important to create a System DSN instead of an User DNS,
3076 otherwise the ODBC backend cannot function.
3078 Press Add..., then you have to select a driver.
3080 Select Microsoft Access Driver (*.mdb).
3082 Use PowerDNS as the DSN name, you can leave the description empty.
3084 Then press Select... to select the database (ie. C:\Program
3085 Files\PowerDNS\powerdns.mdb).
3087 Press Ok and you should be done.
3089 For more information, see Section A.10.
3091 ----------------------------------------------------------------------
3093 3.1. Configuring PDNS on Microsoft Windows
3095 \r You can specify program parameters in the pdns.conf file which should be
3096 located in pdns directory (ie. C:\Program Files\PowerDNS\).
3098 \r To see a list of available parameters you can run pdns.exe --help.
3100 Note
\r A default configuration file has been supplied with the
3103 ----------------------------------------------------------------------
3105 3.2. Running PDNS on Microsoft Windows
3107 If you installed pdns on Windows NT, 2000 or XP you can run pdns as a
3110 This is how to do it: Go to services (Start->Settings->Control
3111 Panel->Administrative Tools->Services) and locate PDNS (you should have
3112 registered the program as a NT service during the installation).
3114 Double-click on PDNS and push the start button. You should now see a
3115 progress bar that gets to the end and see the status change to 'Started'.
3117 This is the same as starting pdns like this: pdns.exe --ntservice
3119 If you haven't registered pdns as a service during the installation you
3120 can do so from the commandline by starting pdns like this: pdns.exe
3123 You can run pdns as a standard console program by using a command prompt
3124 or Start->Run... This way you can specify command-line parameters (see the
3125 documentation for commandline options).
3127 If you chose to add a PowerDNS menu to the start menu during the
3128 installation you can start pdns using the pdns shortcut in that menu.
3130 ----------------------------------------------------------------------
3132 Chapter 4. Configure database connectivity
3134 This chapter shows you how to configure the Generic MySQL backend, which
3135 we like a lot. But feel free to use any of the myriad other backends. This
3136 backend is called 'gmysql', and needs to be configured in pdns.conf. Add
3137 the following lines, adjusted for your local setup:
3140 gmysql-host=127.0.0.1
3142 gmysql-dbname=pdnstest
3145 Remove any earlier launch statements. Also remove the bind-example-zones
3146 statement as the bind module is no longer launched.
3148 Warning Make sure that you can actually resolve the hostname of your
3149 database without accessing the database! It is advised to supply
3150 an IP address here to prevent chicken/egg problems!
3152 Warning Be very very sure that you configure the *g*mysql backend and not
3153 the mysql backend. See Section A.5. If you use the 'mysql' backend
3154 things will only appear to work.
3156 Now start PDNS using the monitor command:
3158 # /etc/init.d/pdns monitor
3160 15:31:30 PowerDNS 1.99.0 (Mar 12 2002, 15:00:28) starting up
3161 15:31:30 About to create 3 backend threads
3162 15:31:30 [gMySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
3163 15:31:30 [gMySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
3164 15:31:30 [gMySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
3167 This is as to be expected - we did not yet add anything to MySQL for PDNS
3168 to read from. At this point you may also see other errors which indicate
3169 that PDNS either could not find your MySQL server or was unable to connect
3170 to it. Fix these before proceeding.
3172 General MySQL knowledge is assumed in this chapter, please do not
3173 interpret these commands as DBA advice!
3175 ----------------------------------------------------------------------
3177 4.1. Configuring MySQL
3179 Connect to MySQL as a user with sufficient privileges and issue the
3182 create table domains (
3183 id INT auto_increment,
3184 name VARCHAR(255) NOT NULL,
3185 master VARCHAR(20) DEFAULT NULL,
3186 last_check INT DEFAULT NULL,
3187 type VARCHAR(6) NOT NULL,
3188 notified_serial INT DEFAULT NULL,
3189 account VARCHAR(40) DEFAULT NULL,
3193 CREATE UNIQUE INDEX name_index ON domains(name);
3195 CREATE TABLE records (
3196 id INT auto_increment,
3197 domain_id INT DEFAULT NULL,
3198 name VARCHAR(255) DEFAULT NULL,
3199 type VARCHAR(6) DEFAULT NULL,
3200 content VARCHAR(255) DEFAULT NULL,
3201 ttl INT DEFAULT NULL,
3202 prio INT DEFAULT NULL,
3203 change_date INT DEFAULT NULL,
3207 CREATE INDEX rec_name_index ON records(name);
3208 CREATE INDEX nametype_index ON records(name,type);
3209 CREATE INDEX domain_id ON records(domain_id);
3211 create table supermasters (
3212 ip VARCHAR(25) NOT NULL,
3213 nameserver VARCHAR(255) NOT NULL,
3214 account VARCHAR(40) DEFAULT NULL
3217 GRANT SELECT ON supermasters TO pdns;
3218 GRANT ALL ON domains TO pdns;
3219 GRANT ALL ON records TO pdns;
3222 Now we have a database and an empty table. PDNS should now be able to
3223 launch in monitor mode and display no errors:
3225 # /etc/init.d/pdns monitor
3227 15:31:30 PowerDNS 1.99.0 (Mar 12 2002, 15:00:28) starting up
3228 15:31:30 About to create 3 backend threads
3229 15:39:55 [gMySQLbackend] MySQL connection succeeded
3230 15:39:55 [gMySQLbackend] MySQL connection succeeded
3231 15:39:55 [gMySQLbackend] MySQL connection succeeded
3234 A sample query sent to the database should now return quickly without
3237 $ host www.test.com 127.0.0.1
3238 www.test.com A record currently not present at localhost
3241 And indeed, the control console now shows:
3243 Mar 12 15:41:12 We're not authoritative for 'www.test.com', sending unauth normal response
3246 Now we need to add some records to our database:
3249 mysql> INSERT INTO domains (name, type) values ('test.com', 'NATIVE');
3250 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3251 VALUES (1,'test.com','localhost ahu@ds9a.nl 1','SOA',86400,NULL);
3252 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3253 VALUES (1,'test.com','dns-us1.powerdns.net','NS',86400,NULL);
3254 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3255 VALUES (1,'test.com','dns-eu1.powerdns.net','NS',86400,NULL);
3256 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3257 VALUES (1,'www.test.com','199.198.197.196','A',120,NULL);
3258 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3259 VALUES (1,'mail.test.com','195.194.193.192','A',120,NULL);
3260 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3261 VALUES (1,'localhost.test.com','127.0.0.1','A',120,NULL);
3262 INSERT INTO records (domain_id, name, content, type,ttl,prio)
3263 VALUES (1,'test.com','mail.test.com','MX',120,25);
3266 If we now requery our database, www.test.com should be present:
3268 $ host www.test.com 127.0.0.1
3269 www.test.com A 199.198.197.196
3271 $ host -v -t mx test.com 127.0.0.1
3275 Query about test.com for record types MX
3277 Query done, 1 answer, authoritative status: no error
3278 test.com 120 IN MX 25 mail.test.com
3279 Additional information:
3280 mail.test.com 120 IN A 195.194.193.192
3283 To confirm what happened, issue the command SHOW * to the control console:
3286 corrupt-packets=0,latency=0,packetcache-hit=2,packetcache-miss=5,packetcache-size=0,
3287 qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,tcp-queries=0,
3288 timedout-packets=0,udp-answers=7,udp-queries=7,
3292 The actual numbers will vary somewhat. Now enter QUIT and start PDNS as a
3293 regular daemon, and check launch status:
3295 # /etc/init.d/pdns start
3297 # /etc/init.d/pdns status
3298 pdns: 8239: Child running
3299 # /etc/init.d/pdns dump
3300 pdns: corrupt-packets=0,latency=0,packetcache-hit=0,packetcache-miss=0,
3301 packetcache-size=0,qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,
3302 tcp-queries=0,timedout-packets=0,udp-answers=0,udp-queries=0,
3305 You now have a working database driven nameserver! To convert other zones
3306 already present, use the zone2sql described in Appendix A.
3308 ----------------------------------------------------------------------
3310 4.1.1. Common problems
3312 Most problems involve PDNS not being able to connect to the database.
3314 Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)
3316 Your MySQL installation is probably defaulting to another location
3317 for its socket. Can be resolved by figuring out this location
3318 (often /var/run/mysqld.sock), and specifying it in the
3319 configuration file with the gmysql-socket parameter.
3321 Another solution is to not connect to the socket, but to
3322 127.0.0.1, which can be achieved by specifying
3323 gmysql-host=127.0.0.1.
3325 Host 'x.y.z.w' is not allowed to connect to this MySQL server
3327 These errors are generic MySQL errors. Solve them by trying to
3328 connect to your MySQL database with the MySQL console utility
3329 mysql with the parameters specified to PDNS. Consult the MySQL
3332 ----------------------------------------------------------------------
3334 Chapter 5. Dynamic resolution using the PipeBackend
3336 Also included in the PDNS distribution is the PipeBackend. The PipeBackend
3337 is primarily meant for allowing rapid development of new backends without
3338 tight integration with PowerDNS. It allows end-users to write PDNS
3339 backends in any language. A perl sample is provided. The PipeBackend is
3340 also very well suited for dynamic resolution of queries. Example
3341 applications include DNS based loadbalancing, geo-direction, DNS based
3342 failover with low TTLs.
3344 The Pipe Backend also has a separate chapter in the backends appendix, see
3347 Note The Pipe Backend currently does not function under FreeBSD 4.x and
3348 5.x, probably due to unfavorable interactions between its threading
3349 implementation and the fork system call.
3351 Interestingly, the Linux PowerDNS binary running under the
3352 Linuxulator on FreeBSD does work.
3354 ----------------------------------------------------------------------
3356 5.1. Deploying the PipeBackend with the BindBackend
3358 Included with the PDNS distribution is the example.pl backend which has
3359 knowledge of the example.com zone, just like the BindBackend. To install
3360 both, add the following to your pdns.conf:
3364 pipe-command=location/of/backend.pl
3367 Please adjust the pipe-command statement to the location of the unpacked
3368 PDNS distribution. If your backend is slow, raise pipe-timeout from its
3369 default of 2000ms. Now launch PDNS in monitor mode, and perform some
3370 queries. Note the difference with the earlier experiment where only the
3371 BindBackend was loaded. The PipeBackend is launched first and thus gets
3372 queried first. The sample backend.pl script knows about:
3374 * webserver.example.com A records pointing to 1.2.3.4, 1.2.3.5, 1.2.3.6
3376 * www.example.com CNAME pointing to webserver.example.com
3378 * MBOXFW (mailbox forward) records pointing to powerdns@example.com. See
3379 the smtpredir documentation for information about MBOXFW.
3381 For more information about how to write exciting backends with the
3382 PipeBackend, see Appendix A.
3384 ----------------------------------------------------------------------
3386 Chapter 6. Logging & Monitoring PDNS performance
3388 In a production environment, you will want to be able to monitor PDNS
3389 performance. For this purpose, currently two methods are available, the
3390 webserver and the init.d dump, show and mrtg, commands. Furthermore, PDNS
3391 can perform a configurable amount of operational logging. This chapter
3392 also explains how to configure syslog for best results.
3394 ----------------------------------------------------------------------
3398 To launch the internal webserver, add a webserver statement to the
3399 pdns.conf. This will instruct the PDNS daemon to start a webserver on
3400 localhost at port 8081, without password protection. Only local users (on
3401 the same host) will be able to access the webserver by default. The
3402 webserver lists a lot of information about the PDNS process, including
3403 frequent queries, frequently failing queries, lists of remote hosts
3404 sending queries, hosts sending corrupt queries etc. The webserver does not
3405 allow remote management of the daemon. The following nameserver related
3406 configuration items are available:
3410 If set to anything but 'no', a webserver is launched.
3414 Address to bind the webserver to. Defaults to 127.0.0.1, which
3415 implies that only the local computer is able to connect to the
3416 nameserver! To allow remote hosts to connect, change to 0.0.0.0 or
3417 the physical IP address of your nameserver.
3421 If set, viewers will have to enter this plaintext password in
3422 order to gain access to the statistics.
3426 Port to bind the webserver to. Defaults to 8081.
3428 ----------------------------------------------------------------------
3430 6.2. Via init.d commands
3432 As mentioned before, the init.d commands dump, show and mrtg fetch data
3433 from a running PDNS process. Especially mrtg is powerful - it outputs data
3434 in a format that is ready for processing by the MRTG graphing tool.
3436 MRTG can make insightful graphics on the performance of your nameserver,
3437 enabling the operator to easily spot trends. MRTG can be found on
3438 http://people.ee.ethz.ch/~oetiker/webtools/mrtg/mrtg.html
3443 WorkDir: /var/www/mrtg
3445 Options[_]: growright,nopercent
3448 #---------------------------------------------------------------
3450 Target[udp-queries]: `/etc/init.d/pdns mrtg udp-queries udp-answers`
3451 Options[udp-queries]: growright,nopercent,perminute
3452 MaxBytes[udp-queries]: 600000
3453 AbsMax[udp-queries]: 600000
3454 Title[udp-queries]: Queries per minute
3455 PageTop[udp-queries]: <H2>Queries per minute</H2>
3456 WithPeak[udp-queries]: ymwd
3457 YLegend[udp-queries]: queries/minute
3458 ShortLegend[udp-queries]: q/m
3459 LegendI[udp-queries]: udp-questions
3460 LegendO[udp-queries]: udp-answers
3463 Target[perc-failed]: `/etc/init.d/pdns mrtg udp-queries udp-answers`
3464 Options[perc-failed]: growright,dorelpercent,perminute
3465 MaxBytes[perc-failed]: 600000
3466 AbsMax[perc-failed]: 600000
3467 Title[perc-failed]: Queries per minute, with percentage success
3468 PageTop[perc-failed]: <H2>Queries per minute, with percentage success</H2>
3469 WithPeak[perc-failed]: ymwd
3470 YLegend[perc-failed]: queries/minute
3471 ShortLegend[perc-failed]: q/m
3472 LegendI[perc-failed]: udp-questions
3473 LegendO[perc-failed]: udp-answers
3476 Target[packetcache-rate]: `/etc/init.d/pdns mrtg packetcache-hit udp-queries`
3477 Options[packetcache-rate]: growright,dorelpercent,perminute
3478 Title[packetcache-rate]: packetcache hitrate
3479 MaxBytes[packetcache-rate]: 600000
3480 AbsMax[packetcache-rate]: 600000
3481 PageTop[packetcache-rate]: <H2>packetcache hitrate</H2>
3482 WithPeak[packetcache-rate]: ymwd
3483 YLegend[packetcache-rate]: queries/minute
3484 ShortLegend[packetcache-rate]: q/m
3485 LegendO[packetcache-rate]: total
3486 LegendI[packetcache-rate]: hit
3488 Target[packetcache-missrate]: `/etc/init.d/pdns mrtg packetcache-miss udp-queries`
3489 Options[packetcache-missrate]: growright,dorelpercent,perminute
3490 Title[packetcache-missrate]: packetcache MISSrate
3491 MaxBytes[packetcache-missrate]: 600000
3492 AbsMax[packetcache-missrate]: 600000
3493 PageTop[packetcache-missrate]: <H2>packetcache MISSrate</H2>
3494 WithPeak[packetcache-missrate]: ymwd
3495 YLegend[packetcache-missrate]: queries/minute
3496 ShortLegend[packetcache-missrate]: q/m
3497 LegendO[packetcache-missrate]: total
3498 LegendI[packetcache-missrate]: MISS
3500 Target[latency]: `/etc/init.d/pdns mrtg latency`
3501 Options[latency]: growright,nopercent,gauge
3502 MaxBytes[latency]: 600000
3503 AbsMax[latency]: 600000
3504 Title[latency]: Query/answer latency
3505 PageTop[latency]: <H2>Query/answer latency</H2>
3506 WithPeak[latency]: ymwd
3507 YLegend[latency]: usec
3508 ShortLegend[latency]: usec
3509 LegendO[latency]: latency
3510 LegendI[latency]: latency
3512 Target[recursing]: `/etc/init.d/pdns mrtg recursing-questions recursing-answers`
3513 Options[recursing]: growright,nopercent,gauge
3514 MaxBytes[recursing]: 600000
3515 AbsMax[recursing]: 600000
3516 Title[recursing]: Recursive questions/answers
3517 PageTop[recursing]: <H2>Recursing questions/answers</H2>
3518 WithPeak[recursing]: ymwd
3519 YLegend[recursing]: queries/minute
3520 ShortLegend[recursing]: q/m
3521 LegendO[recursing]: recursing-questions
3522 LegendI[recursing]: recursing-answers
3526 ----------------------------------------------------------------------
3528 6.3. Operational logging using syslog
3530 (logging-facility is available from 1.99.10 and onwards)
3532 This chapter assumes familiarity with syslog, the unix logging device.
3533 PDNS logs messages with different levels. The more urgent the message, the
3534 lower the 'priority'. By default, PDNS will only log messages with an
3535 urgency of 3 or lower, but this can be changed using the loglevel setting
3536 in the configuration file. Setting it to 0 will eliminate all logging, 9
3537 will log everything.
3539 By default, logging is performed under the 'DAEMON' facility which is
3540 shared with lots of other programs. If you regard nameserving as
3541 important, you may want to have it under a dedicated facility so PDNS can
3542 log to its own files, and not clutter generic files.
3544 For this purpose, syslog knows about 'local' facilities, numbered from
3545 LOCAL0 to LOCAL7. To move PDNS logging to LOCAL0, add logging-facility=0
3546 to your configuration.
3548 Furthermore, you may want to have separate files for the differing
3549 prioties - preventing lower priority messages from obscuring important
3552 A sample syslog.conf might be:
3554 local0.info -/var/log/pdns.info
3555 local0.warn -/var/log/pdns.warn
3556 local0.err /var/log/pdns.err
3559 Where local0.err would store the really important messages. For
3560 performance and diskspace reasons, it is advised to audit your syslog.conf
3561 for statements also logging PDNS activities. Many syslog.confs have a
3562 '*.*' statement to /var/log/syslog, which you may want to remove.
3564 For performance reasons, be especially certain that no large amounts of
3565 synchronous logging take place. Under Linux, this is indicated by
3566 filenames not starting with a '-' - indicating a synchronous log, which
3569 ----------------------------------------------------------------------
3571 Chapter 7. Security settings & considerations
3575 PDNS has several options to easily allow it to run more securely. Most
3576 notable are the chroot, setuid and setgid options which can be specified.
3578 ----------------------------------------------------------------------
3580 7.1.1. Running as a less privileged identity
3582 By specifying setuid and setgid, PDNS changes to this identity shortly
3583 after binding to the privileged DNS ports. These options are highly
3584 recommended. It is suggested that a separate identity is created for PDNS
3585 as the user 'nobody' is in fact quite powerful on most systems.
3587 Both these parameters can be specified either numerically or as real
3588 names. You should set these parameters immediately if they are not set!
3590 ----------------------------------------------------------------------
3592 7.1.2. Jailing the process in a chroot
3594 The chroot option secures PDNS to its own directory so that even if it
3595 should become compromised and under control of external influences, it
3596 will have a hard time affecting the rest of the system.
3598 Even though this will hamper hackers a lot, chroot jails have been known
3601 Warning When chrooting PDNS, take care that backends will be able to get
3602 to their files. Many databases need access to a UNIX domain socket
3603 which should live within the chroot. It is often possible to
3604 hardlink such a socket into the chroot dir.
3606 When running with master or slave support, be aware that many
3607 operating systems need access to specific libraries (ofen
3608 /lib/libnss*) in order to support resolution of domain names! You
3609 can also hardlink these.
3611 The default PDNS configuration is best chrooted to ./, which boils down to
3612 the configured location of the controlsocket.
3614 This is achieved by adding the following to pdns.conf: chroot=./, and
3617 ----------------------------------------------------------------------
3621 In general, make sure that the PDNS process is unable to execute commands
3622 on your backend database. Most database backends will only need SELECT
3623 privilege. Take care to not connect to your database as the 'root' or 'sa'
3624 user, and configure the chosen user to have very slight privileges.
3626 Databases empathic-ally do not need to run on the same machine that runs
3627 PDNS! In fact, in benchmarks it has been discovered that having a separate
3628 database machine actually improves performance.
3630 Separation will enhance your database security highly. Recommended.
3632 ----------------------------------------------------------------------
3634 Chapter 8. Virtual hosting
3636 It may be advantageous to run multiple separate PDNS installations on a
3637 single host, for example to make sure that different customers cannot
3638 affect each others zones. PDNS fully supports running multiple instances
3641 To generate additional PDNS instances, copy the init.d script pdns to
3642 pdns-name, where name is the name of your virtual configuration. Must not
3643 contain a - as this will confuse the script.
3645 When you launch PDNS via this renamed script, it will seek configuration
3646 instructions not in pdns.conf but in pdns-name.conf, allowing for separate
3647 specification of parameters.
3649 Be aware however that the init.d force-stop will kill all PDNS instances!
3651 ----------------------------------------------------------------------
3653 Chapter 9. Performance related settings
3655 Different backends will have different characteristics - some will want to
3656 have more parallel instances than others. In general, if your backend is
3657 latency bound, like most relational databases are, it pays to open more
3660 This is done with the distributor-threads setting. Of special importance
3661 is the choice between 1 or more backends. In case of only 1 thread, PDNS
3662 reverts to unthreaded operation which may be a lot faster, depending on
3663 your operating system and architecture.
3665 Another very important setting cache-ttl. PDNS caches entire packets it
3666 sends out so as to save the time to query backends to assemble all data.
3667 The default setting of 10 seconds may be low for high traffic sites, a
3668 value of 60 seconds rarely leads to problems.
3670 Some PDNS operators set cache-ttl to many hours or even days, and use
3671 pdns_control purge to selectively or globally notify PDNS of changes made
3672 in the backend. Also look at the Query Cache described in this chapter. It
3673 may materially improve your performance.
3675 To determine if PDNS is unable to keep up with packets, determine the
3676 value of the qsize-q variable. This represents the number of packets
3677 waiting for database attention. During normal operations the queue should
3680 If it is known that backends will not contain CNAME records, the
3681 skip-cname setting can be used to prevent the normally mandatory CNAME
3682 lookup that is needed at least once for each DNS query.
3684 Much the same holds for the wildcards setting. On by default, each
3685 non-existent query will lead to a number of additional wildcard queries.
3686 If it is known that the backends do not contain wildcard records,
3687 performance can be improved by adding wildcards=no to pdns.conf.
3689 Logging truly kills performance as answering a question from the cache is
3690 an order of magnitude less work than logging a line about it. Busy sites
3691 will prefer to turn log-dns-details and log-failed-updates off.
3693 ----------------------------------------------------------------------
3697 PDNS by default uses the 'Packet Cache' to recognise identical questions
3698 and supply them with identical answers, without any further processing.
3699 The default time to live is 10 seconds. It has been observed that the
3700 utility of the packet cache increases with the load on your nameserver.
3702 Not all backends may benefit from the packetcache. If your backend is
3703 memory based and does not lead to context switches, the packetcache may
3704 actually hurt performance.
3706 The size of the packetcache can be observed with /etc/init.d/pdns show
3709 ----------------------------------------------------------------------
3713 Besides entire packets, PDNS can also cache individual backend queries.
3714 Each DNS query leads to a number of backend queries, the most obvious
3715 additional backend query is the check for a possible CNAME. So, when a
3716 query comes in for the 'A' record for 'www.powerdns.com', PDNS must first
3717 check for a CNAME for 'www.powerdns.com'.
3719 The Query Cache caches these backend queries, many of which are quite
3720 repetitive. PDNS only caches queries with no answer, or with exactly one.
3721 In the future this may be expanded but this lightweight solution is very
3722 simple and therefore fast.
3724 Most gain is made from caching negative entries, ie, queries that have no
3725 answer. As these take little memory to store and are typically not a real
3726 problem in terms of speed-of-propagation, the default TTL for negative
3727 queries is a rather high 60 seconds.
3729 This only is a problem when first doing a query for a record, adding it,
3730 and immediately doing a query for that record again. It may then take up
3731 to 60 seconds to appear. Changes to existing records however do not fall
3732 under the negative query ttl ( negquery-cache-ttl), but under the generic
3733 query-ttl which defaults to 20 seconds.
3735 The default values should work fine for many sites. When tuning, keep in
3736 mind that the Query Cache mostly saves database access but that the Packet
3737 Cache also saves a lot of CPU because 0 internal processing is done when
3738 answering a question from the Packet Cache.
3740 ----------------------------------------------------------------------
3742 Chapter 10. Migrating to PDNS
3744 Before migrating to PDNS a few things should be considered.
3746 PDNS is not a recursing nameserver on its own
3748 If PDNS receives a question for which it is not authoritative, it
3749 can't go out on the net to figure out an answer. However, because
3750 many installations are expected to be both authoritative and
3751 recursing, PDNS can use a separate recursing backend to provide
3752 non-authoritative answers. See Chapter 11 for more details.
3754 PDNS does not operate as a 'slave' or 'master' server with all backends
3756 Only the Generic PostgreSQL, Generic MySQL and BIND backends have
3757 the ability to act as master or slave.
3759 To migrate, the zone2sql tool is provided.
3761 ----------------------------------------------------------------------
3765 Zone2sql parses Bind named.conf files and zonefiles and outputs SQL on
3766 standard out, which can then be fed to your database.
3768 Zone2sql understands the Bind master file extension '$GENERATE' and will
3769 also honour '$ORIGIN' and '$TTL'.
3771 For backends supporting slave operation (currently only the Generic
3772 PostgreSQL, Generic MySQL and BIND backend), there is also an option to
3773 keep slave zones as slaves, and not convert them to native operation.
3775 By default, zone2sql outputs code suitable for the mysqlbackend, but it
3776 can also generate SQL for the Generic PostgreSQL, Generic MySQL and Oracle
3777 backends. The following commands are available:
3781 Output in a bare format, suitable for further parsing. The output
3782 is formatted as follows:
3784 domain_id<TAB>'qname'<TAB>'qtype'<TAB>'content'<TAB>prio<TAB>ttl
3789 Output in format suitable for the default configuration of the
3790 Generic MySQL backend.
3794 Output in format suitable for the default configuration of the
3795 Generic PostgreSQL backend.
3803 Output in format suitable for the default configuration of the
3804 MySQL backend. Default.
3808 Parse this named.conf to find locations of zones.
3810 --on-error-resume-next
3812 Ignore missing files during parsing. Dangerous.
3816 Output in format suitable for the default configuration of the
3817 Generic Oracle backend.
3821 Maintain slave status of zones listed in named.conf as being
3822 slaves. The default behaviour is to convert all zones to native
3827 Supply a value for the first domain_id generated. Defaults at 0.
3831 For Oracle and PostgreSQL output, wrap each domain in a
3832 transaction for higher speed and integrity.
3836 Be verbose during conversion.
3840 Parse only this zone file. Conflicts with --named-conf parameter.
3844 When parsing a single zone without $ORIGIN statement, set this as
3847 ----------------------------------------------------------------------
3849 Chapter 11. Recursion
3851 (only available from 1.99.8 and onwards, recursing component available
3854 From 2.9.5 onwards, PowerDNS offers both authoritative nameserving
3855 capabilities and a recursive nameserver component. These two halves are
3856 normally separate but many users insist on combining both recursion and
3857 authoritative service on one IP address. This can be likened to running
3858 Apache and Squid both on port 80.
3860 However, many sites want to do this anyhow and some with good reason. For
3861 example, a setup like this allows the creation of fake domains which only
3862 exist for local users. Such domains often don't end on ".com" or ".org"
3863 but on ".intern" or ".name-of-isp".
3865 PowerDNS can cooperate with either its own recursor or any other you have
3866 available to deliver recursive service on its port.
3868 By specifying the recursor option in the configuration file, questions
3869 requiring recursive treatment will be handed over to the IP address
3870 specified. An example configuration might be recursor=130.161.180.1, which
3871 designates 130.161.180.1 as the nameserver to handle recursive queries.
3873 As of 2.9.5, the recursing component of PowerDNS is a bit young and
3874 relatively untested but we hope people will want to use it anyhow. As an
3875 alternative, we highly advise the use of the DJBDNS dnscache
3876 (http://cr.yp.to/djbdns/dnscache.html).
3878 Take care not to point recursor to PDNS, which leads to a very tight
3881 By specifying allow-recursion, recursion can be restricted to netmasks
3882 specified. The default is to allow recursion from everywhere. Example:
3883 allow-recursion=192.168.0.0/24, 10.0.0.0/8, 1.2.3.4.
3885 ----------------------------------------------------------------------
3889 Questions carry a number of flags. One of these is called 'Recursion
3890 Desired'. If PDNS is configured to allow recursion, AND such a flag is
3891 seen, AND the IP address of the client is allowed to recurse via PDNS,
3892 then the packet may be handed to the recursing backend.
3894 If a Recursion Desired packet arrives and PDNS is configured to allow
3895 recursion, but not to the IP address of the client, resolution will
3896 proceed as if the RD flag were unset and the answer will indicate that
3897 recursion was not available.
3899 It is also possible to use a resolver living on a different port. To do
3900 so, specify a recursor like this: recursor=130.161.180.1:5300.
3902 If the backend does not answer a question within a large amount of time,
3903 this is logged as 'Recursive query for remote 10.96.0.2 with internal id 0
3904 was not answered by backend within timeout, reusing id'. This may happen
3905 when using 'BIND' as a recursor as it is prone to drop queries which it
3906 can't answer immediately.
3908 To make sure that the local authoritative database overrides recursive
3909 information, PowerDNS first tries to answer a question from its own
3910 database. If that succeeds, the answer packet is sent back immediately
3911 without involving the recursor in any way. This means that for questions
3912 for which there is no answer, PowerDNS will consult the recursor for an
3913 recursive query, even if PowerDNS is authoritative for a domain! This will
3914 only cause problems if you 'fake' domains which don't really exist.
3916 If you want to create such fake domains or override existing domains,
3917 please set the allow-recursion-override feature (available as of 2.9.14).
3919 Some packets, like those asking for MX records which are needed for SMTP
3920 transport of email, can be subject to 'additional processing'. This means
3921 that a recursing nameserver is obliged to try to add A records (IP
3922 addresses) for any of the mailservers mentioned in the packet, should it
3923 have these addresses available.
3925 If PowerDNS encounters records needing such processing and finds that it
3926 does not have the data in its authoritative database, it will send an
3927 opportunistic quick query to the recursing component to see if it perhaps
3928 has such data. This question is worded such that the recursing nameserver
3929 should return immediately such as not to block the authoritative
3932 This marks a change from pre-2.9.5 behaviour where a packet was handed
3933 wholesale to the recursor in case it needed additional processing which
3934 could not proceed from the authoritative database.
3936 ----------------------------------------------------------------------
3938 Chapter 12. PowerDNS resolver/recursing nameserver
3940 As of 2.9.4, a small recursor comes with PowerDNS. The algorithm is
3941 influenced by the works of Dan J. Bernstein although all mistakes are
3942 ours. Here are the current faults, so nobody can accuse us of false
3945 * Only compiles on Linux, Windows and possibly Solaris. FreeBSD 4.x
3946 decided not to support the POSIX get/set/swapcontext functions. Bug
3947 your favorite FreeBSD kernel or libc maintainer for a fix, or ask him
3948 to port MTasker (see below) to your operating system.
3950 * May have big problems with truncated packets.
3952 To compile, add --enable-recursor to configure and the file pdns_recursor
3953 will be compiled. To run on a different port, use ./syncres
3954 --local-port=53. To bind to another address, use the local-address
3957 Note PowerDNS author bert hubert has the pdns recursor in production and
3958 browsing with it works for him. Furthermore, the LARTC mailinglist
3959 (2000 subscribers) is using the pdns recursing nameserver.
3963 * Uses MTasker (homepage)
3965 * Can handle thousands of concurrent questions
3967 * Code is written linearly, sequentially, which means that there are no
3968 problems with 'query restart' or anything.
3970 * Relies heavily on Standard C++ Library infrastructure, which makes for
3971 little code (406 core lines).
3973 * Is very verbose in showing how recursion actually works.
3975 * The algorithm is simple and quite nifty.
3977 ----------------------------------------------------------------------
3979 12.1. pdns_recursor settings
3981 At startup, the recursing nameserver reads the file recursor.conf from the
3982 configuration directory, often /etc/powerdns or /usr/local/etc.
3984 The following settings can be configured:
3986 aaaa-additional-processing
3988 If turned on, the recursor will attempt to add AAAA IPv6 records
3989 to questions for MX records and NS records. Can be quite slow as
3990 absence of these records in earlier answers does not guarantee
3991 their non-existance. Can double the amount of queries needed. Off
3996 Directory where the configuration file can be found.
4000 Operate in the background, which is the default.
4004 A Verisign special, see Section 12.1.1.
4008 Local IP address (singular) to bind to. Defaults to all addresses.
4012 Local port (singular) to bind to. Defaults to 53.
4020 If turned on, output impressive heaps of logging. May destroy
4021 performance under load.
4023 ----------------------------------------------------------------------
4025 12.1.1. Verisign weirdness
4027 Verisign, the current operator of the COM and NET zones, decided to add a
4028 wildcard record so as to draw all queries for non-existing domains to
4029 their own page, which lists domains you might want to visist instead.
4031 To reinstate old behaviour, add delegation-only=com,net to your recursor
4034 What this does is reject all authoritative answers from the COM and NET
4035 servers. ISC, the current maintainers of BIND, have implemented this
4036 feature first, PowerDNS has mostly copied their algorithm. Thanks!
4038 Verisign might decide to evade our tactic with wildcard NS records, by
4039 which time other measures will be needed to restore the old behaviour.
4041 ----------------------------------------------------------------------
4045 PowerDNS implements a very simple but effective nameserver. Care has been
4046 taken not to overload remote servers in case of overly active clients.
4048 This is implemented using the 'throttle'. This accounts all recent traffic
4049 and prevents queries that have been sent out recently from going out
4052 There are three levels of throttling.
4054 * If a remote server indicates that it is lame for a zone, the exact
4055 question won't be repeated in the next 60 seconds.
4057 * After 4 ServFail responses in 60 seconds, the query gets throttled
4060 * 5 timeouts in 20 seconds also lead to query suppression.
4062 ----------------------------------------------------------------------
4066 Every half our or so, the recursor outputs a line with statistics. More
4067 infrastructure is planned so as to allow for Cricket or MRTG graphs. To
4068 force the output of statistics, send the process a SIGUSR1. A line of
4069 statistics looks like this:
4071 Feb 10 14:16:03 stats: 125784 questions, 13971 cache entries, 309 negative entries, 84% cache hits, outpacket/query ratio 37%, 12% throttled
4073 This means that there are 13791 different names cached, which each may
4074 have multiple records attached to them. There are 309 items in the
4075 negative cache, items of which it is known that don't exist and won't do
4076 so for the near future. 84% of incoming questions could be answered
4077 without any additional queries going out to the net.
4079 The outpacket/query ratio means that on average, 0.37 packets were needed
4080 to answer a question. Initially this ratio may be well over 100% as
4081 additional queries may be needed to actually recurse the DNS and figure
4082 out the addresses of nameservers.
4084 Finally, 12% of queries were not performed because identical queries had
4085 gone out previously, saving load servers worldwide.
4087 ----------------------------------------------------------------------
4089 Chapter 13. Master/Slave operation & replication
4091 PDNS offers full master and slave semantics for replicating domain
4092 information. Furthermore, PDNS can benefit from native database
4095 ----------------------------------------------------------------------
4097 13.1. Native replication
4099 Native replication is the default, unless other operation is specifically
4100 configured. Native replication basically means that PDNS will not send out
4101 DNS update notifications, nor will react to them. PDNS assumes that the
4102 backend is taking care of replication unaided.
4104 MySQL replication has proven to be very robust and well suited, even over
4105 transatlantic connections between badly peering ISPs. Other PDNS users
4106 employ Oracle replication which also works very well.
4108 To use native replication, configure your backend storage to do the
4109 replication and do not configure PDNS to do so.
4111 ----------------------------------------------------------------------
4113 13.2. Slave operation
4115 On launch, PDNS requests from all backends a list of domains which have
4116 not been checked recently for changes. This should happen every 'refresh'
4117 seconds, as specified in the SOA record. All domains that are unfresh are
4118 then checked for changes over at their master. If the SOA serial number
4119 there is higher, the domain is retrieved and inserted into the database.
4120 In any case, after the check the domain is declared 'fresh', and will only
4121 be checked again after 'refresh' seconds have passed.
4123 Warning Slave support is OFF by default, turn it on by adding slave to the
4124 configuration. The same holds for master operation. Both can be on
4127 PDNS also reacts to notifies by immediately checking if the zone has
4128 updated and if so, retransfering it.
4130 All backends which implement this feature must make sure that they can
4131 handle transactions so as to not leave the zone in a half updated state.
4132 MySQL configured with either BerkeleyDB or InnoDB meets this requirement,
4133 as do PostgreSQL and Oracle. The Bindbackend implements transaction
4134 semantics by renaming files if and only if they have been retrieved
4135 completely and parsed correctly.
4137 Slave operation can also be programmed using several pdns_control
4138 commands, see Section B.1.1. The 'retrieve' command is especially useful
4139 as it triggers an immediate retrieval of the zone from the configured
4142 ----------------------------------------------------------------------
4144 13.2.1. Supermaster automatic provisioning of slaves
4146 PDNS can recognize so called 'supermasters'. A supermaster is a host which
4147 is master for domains and for which we are to be a slave. When a master
4148 (re)loads a domain, it sends out a notification to its slaves. Normally,
4149 such a notification is only accepted if PDNS already knows that it is a
4152 However, a notification from a supermaster carries more persuasion. When
4153 PDNS determines that a notification comes from a supermaster and it is
4154 bonafide, PDNS can provision the domain automatically, and configure
4155 itself as a slave for that zone.
4157 To enable this feature, a backend needs to know about the IP address of
4158 the supermaster, and how PDNS will be listed in the set of NS records
4159 remotely, and the 'account' name of your supermaster. There is no need to
4160 fill this out but it does help keep track of where a domain comes from.
4162 ----------------------------------------------------------------------
4164 13.3. Master operation
4166 When operating as a master, PDNS sends out notifications of changes to
4167 slaves, which react to these notifications by querying PDNS to see if the
4168 zone changed, and transferring its contents if it has. Notifications are a
4169 way to promptly propagate zone changes to slaves, as described in RFC
4172 Warning Master support is OFF by default, turn it on by adding master to
4173 the configuration. The same holds for slave operation. Both can be
4176 Left open by RFC 1996 is who is to be notified - which is harder to figure
4177 out than it sounds. All slaves for this domain must receive a notification
4178 but the nameserver only knows the names of the slaves - not the IP
4179 addresses, which is where the problem lies. The nameserver itself might be
4180 authoritative for the name of its secondary, but not have the data
4183 To resolve this issue, PDNS tries multiple tactics to figure out the IP
4184 addresses of the slaves, and notifies everybody. In contrived
4185 configurations this may lead to duplicate notifications being sent out,
4186 which shouldn't hurt.
4188 Some backends may be able to detect zone changes, others may chose to let
4189 the operator indicate which zones have changed and which haven't. Consult
4190 the documentation for your backend to see how it processes changes in
4193 To help deal with slaves that may have missed notifications, or have
4194 failed to respond to them, several override commands are available via the
4195 pdns_control tool (Section B.1.1):
4197 pdns_control notify domain
4199 This instructs PDNS to notify all IP addresses it considers to be
4200 slaves of this domain.
4202 pdns_control notify-host domain ip-address
4204 This is truly an override and sends a notification to an arbitrary
4205 IP address. Can be used in 'also-notify' situations or when PDNS
4206 has trouble figuring out who to notify - which may happen in
4207 contrived configurations.
4209 ----------------------------------------------------------------------
4211 Chapter 14. Fancy records for seamless email and URL integration
4213 PDNS also supports so called 'fancy' records. A Fancy Record is actually
4214 not a DNS record, but it is translated into one. Currently, two fancy
4215 records are implemented, but not very useful without additional unreleased
4216 software. For completeness, they are listed here. The software will become
4217 available later on and is part of the Express and PowerMail suite of
4220 These records imply extra database lookups which has a performance impact.
4221 Therefore fancy records are only queried for if they are enabled with the
4222 fancy-records command in pdns.conf.
4226 This record denotes an email forward. A typical entry looks like
4229 support@yourdomain.com MBOXFW you@yourcompany.com
4232 When PDNS encounters a request for an MX record for yourdomain.com
4233 it will, if fancy records are enabled, also check for the
4234 existence of an MBOXFW record ending on '@yourdomain.com', in
4235 which case it will hand out a record containing the configured
4236 smtpredirector. This server should then also be able to access the
4237 PDNS database to figure out where mail to support@yourdomain.com
4242 URL records work in much the same way, but for HTTP. A sample
4245 yourdomain.com URL http://somewhere.else.com/yourdomain
4248 A URL record is converted into an A record containing the IP
4249 address configured with the urlredirector setting. On that IP
4250 address a webserver should live that knows how to redirect
4251 yourdomain.com to http://somewhere.else.com/yourdomain.
4253 ----------------------------------------------------------------------
4255 Chapter 15. Index of all settings
4257 All PDNS settings are listed here, excluding those that originate from
4258 backends, which are documented in the relevant chapters.
4262 Behaviour pre 2.9.10: When not allowing AXFR (disable-axfr), DO
4263 allow from these IP addresses or netmasks.
4265 Behaviour post 2.9.10: If set, only these IP addresses or netmasks
4266 will be able to perform AXFR.
4270 By specifying allow-recursion, recursion can be restricted to
4271 netmasks specified. The default is to allow recursion from
4272 everywhere. Example: allow-recursion=192.168.0.0/24, 10.0.0.0/8,
4275 allow-recursion-override=on|off
4277 By specifying allow-recursion-override, local data even about
4278 hosts that don't exist will override the internet. This allows you
4279 to generate zones that don't really exist on the internet. Does
4280 increase the number of SQL queries for hosts that truly don't
4281 exist, also not in your database.
4285 Seconds to store packets in the PacketCache. See Section 9.1.
4289 If set, chroot to this directory for more security. See Chapter 7.
4293 Location of configuration directory (pdns.conf)
4297 Name of this virtual configuration - will rename the binary image.
4302 Debugging switch - don't use.
4308 default-soa-name=...
4310 name to insert in the SOA record if none set in the backend
4314 Do not allow zone transfers. Before 2.9.10, this could be
4315 overridden by allow-axfr-ips.
4319 Do not listen to TCP queries. Breaks RFC compliance.
4321 distributor-threads=...
4323 Default number of Distributor (backend) threads to start. See
4328 Process URL and MBOXFW records. See Chapter 14.
4330 guardian | --guardian=yes | --guardian=no
4332 Run within a guardian process. See Section B.2.
4336 Provide a helpful message
4340 Which backends to launch and order to query them in. See Section
4345 On by default as of 2.1. Checks local data first before recursing.
4350 Load this module - supply absolute or relative path. See Section
4355 Local IP address to which we bind. You can specify multiple
4356 addresses separated by commas or whitespace. It is highly advised
4357 to bind to specific interfaces and not use the default 'bind to
4358 any'. This causes big problems if you have multiple IP addresses.
4359 Unix does not provide a way of figuring out what IP address a
4360 packet was sent to when binding to any.
4364 The port on which we listen. Only one port possible.
4366 log-failed-updates=...
4368 If set to 'no', failed Windows Dynamic Updates will not be logged.
4372 If set to 'no', informative-only DNS details will not even be sent
4373 to syslog, improving performance. Available from 2.5 and onwards.
4375 logging-facility=...
4377 If set to a a digit, logging is performed under this LOCAL
4378 facility. See Section 6.3. Available from 1.99.9 and onwards.
4382 Amount of logging. Higher is more. Do not set below 3
4384 max-queue-length=...
4386 If this many packets are waiting for database attention, consider
4387 the situation hopeless and respawn.
4391 Default directory for modules. See Section B.3.
4393 negquery-cache-ttl=...
4395 Seconds to store queries with no answer in the Query Cache. See
4400 Do not attempt to read the configuration file.
4402 out-of-zone-additional-processing |
4403 --out-of-zone-additional-processing=yes |
4404 --out-of-zone-additional-processing=no
4406 Do out of zone additional processing
4410 Seconds to store queries with an answer in the Query Cache. See
4415 Maximum number of miliseconds to queue a query. See Chapter 9.
4417 query-local-address=...
4419 The IP address to use as a source address for sending queries.
4420 Useful if you have multiple IPs and pdns is not bound to the IP
4421 address your operating system uses by default for outgoing
4424 query-logging | query-logging=yes | query-logging=no
4426 Hints to a backend that it should log a textual representation of
4427 queries it performs. Can be set at runtime.
4429 recursive-cache-ttl=...
4431 Seconds to store recursive packets in the PacketCache. See Section
4436 If set, recursive queries will be handed to the recursor specified
4437 here. See Chapter 11.
4441 If set, change group id to this gid for more security. See Chapter
4446 If set, change user id to this uid for more security. See Chapter
4449 skip-cname | --skip-cname=yes | --skip-cname=no
4451 Do not perform CNAME indirection for each query. Has performance
4452 implications. See Chapter 7.
4454 slave-cycle-interval=60
4456 Schedule slave up-to-date checks of domains whose status is
4457 unknown every .. seconds. See Chapter 14.
4461 Our smtpredir MX host. See Chapter 14.
4463 soa-serial-offset=...
4465 If your database contains single-digit SOA serials and you need to
4466 host .DE domains, this setting can help placate their 6-digit SOA
4467 serial requirements. Suggested value is to set this to 1000000
4468 which adds 1000000 to all SOA Serials under that offset.
4472 Where the controlsocket will live. See Section B.1.
4474 strict-rfc-axfrs | --strict-rfc-axfrs=yes | --strict-rfc-axfrs=no
4476 Perform strictly RFC conformant AXFRs, which are slow, but needed
4477 to placate some old client tools.
4481 Where we send hosts to that need to be url redirected. See Chapter
4484 version-string=anonymous|powerdns|full|custom
4486 When queried for its version over DNS (dig chaos txt version.bind
4487 @pdns.ip.address), PowerDNS normally resonds truthfully. With this
4488 setting you can overrule what will be returned. Set the
4489 version-string to 'full' to get the default behaviour, to
4490 'powerdns' to just make it state 'served by PowerDNS -
4491 http://www.powerdns.com'. The 'anonymous' setting will return a
4492 ServFail, much like Microsoft nameservers do. You can set this
4493 response to a custom value as well.
4495 webserver | --webserver=yes | --webserver=no
4497 Start a webserver for monitoring. See Chapter 6.
4499 webserver-address=...
4501 IP Address of webserver to listen on. See Chapter 6.
4503 webserver-password=...
4505 Password required for accessing the webserver. See Chapter 6.
4509 Port of webserver to listen on. See Chapter 6.
4513 Check for wildcard URL records.
4517 Honor wildcards in the database. On by default. Turning this off
4518 has performance implications, see Chapter 9.
4520 ----------------------------------------------------------------------
4522 Chapter 16. Index of all internal metrics
4524 ----------------------------------------------------------------------
4526 16.1. Counters & variables
4528 A number of counters and variables are set during PDNS operation. These
4529 can be queried with the init.d dump, show and mrtg commands, or viewed
4534 Number of corrupt packets received
4538 Average number of microseconds a packet spends within PDNS
4542 Number of packets which were answered out of the cache
4546 Number of times a packet could not be answered out of the cache
4550 Amount of packets in the packetcache
4554 Size of the queue before the transmitting socket.
4558 Number of packets waiting for database attention
4562 Amount of packets that could not be answered due to database
4567 Number of answers sent out over TCP
4571 Number of questions received over TCP
4575 Amount of packets that were dropped because they had to wait too
4580 Number of answers sent out over UDP
4584 Number of questions received over UDP
4586 ----------------------------------------------------------------------
4588 16.1.1. Ring buffers
4590 Besides counters, PDNS also maintains the ringbuffers. A ringbuffer
4591 records events, each new event gets a place in the buffer until it is
4592 full. When full, earlier entries get overwritten, hence the name 'ring'.
4594 By counting the entries in the buffer, statistics can be generated. These
4595 statistics can currently only be viewed using the webserver and are in
4596 fact not even collected without the webserver running.
4598 The following ringbuffers are available:
4600 Log messages (logmessages)
4604 Queries for existing records but for a type we don't have
4607 Queries for, say, the AAAA record of a domain, when only an A is
4608 available. Queries are listed in the following format: name/type.
4609 So an AAA query for pdns.powerdns.com looks like
4610 pdns.powerdns.com/AAAA.
4612 Queries for non-existing records within existing domains(nxdomain-queries)
4614 If PDNS knows it is authoritative over a domain, and it sees a
4615 question for a record in that domain that does not exist, it is
4616 able to send out an authoritative 'no such domain' message.
4617 Indicates that hosts are trying to connect to services really not
4620 UDP queries received (udp-queries)
4622 All UDP queries seen.
4624 Remote server IP addresses (remotes)
4626 Hosts querying PDNS. Be aware that UDP is anonymous - person A can
4627 send queries that appear to be coming from person B.
4629 Remotes sending corrupt packets (remote-corrupts)
4631 Hosts sending PDNS broken packets, possibly meant to disrupt
4632 service. Be aware that UDP is anonymous - person A can send
4633 queries that appear to be coming from person B.
4635 Remotes querying domains for which we are not auth (remote-unauth)
4637 It may happen that there are misconfigured hosts on the internet
4638 which are configured to think that a PDNS installation is in fact
4639 a resolving nameserver. These hosts will not get useful answers
4640 from PDNS. This buffer lists hosts sending queries for domains
4641 which PDNS does not know about.
4643 Queries that could not be answered due to backend errors
4646 For one reason or another, a backend may be unable to extract
4647 answers for a certain domain from its storage. This may be due to
4648 a corrupt database or to inconsistent data. When this happens,
4649 PDNS sends out a 'servfail' packet indicating that it was unable
4650 to answer the question. This buffer shows which queries have been
4653 Queries for domains that we are not authoritative for (unauth-queries)
4655 If a domain is delegated to a PDNS instance, but the backend is
4656 not made aware of this fact, questions come in for which no answer
4657 is available, nor is the authority. Use this ringbuffer to spot
4660 ----------------------------------------------------------------------
4662 Chapter 17. Supported record types and their storage
4664 This chapter lists all record types PDNS supports, and how they are stored
4665 in backends. The list is mostly alphabetical but some types are grouped.
4669 The A record contains an IP address. It is stored as a decimal
4670 dotted quad string, for example: '213.244.168.210'.
4674 The AAAA record contains an IPv6 address. An example:
4675 '3ffe:8114:2000:bf0::1'.
4679 The CNAME record specifies the canonical name of a record. It is
4680 stored plainly. Like all other records, it is not terminated by a
4681 dot. A sample might be 'webserver-01.yourcompany.com'.
4685 Hardware Info record, used to specify CPU and operating system.
4686 Stored with a single space separating these two, example: 'i386
4691 The MX record specifies a mail exchanger host for a domain. Each
4692 mail exchanger also has a priority or preference. This should be
4693 specified in the separate field dedicated for that purpose, often
4698 \r Naming Authority Pointer, RFC 2915. Stored as follows:
4700 '100 50 "s" "z3950+I2L+I2C" "" _z3950._tcp.gatech.edu'.
4703 The fields are: order, preference, flags, service, regex,
4704 replacement. Note that the replacement is not enclosed in quotes,
4705 and should not be. The replacement may be omitted, in which case
4706 it is empty. See also RFC 2916 for how to use NAPTR for ENUM
4711 Nameserver record. Specifies nameservers for a domain. Stored
4712 plainly: 'ns1.powerdns.com', as always without a terminating dot.
4716 Reverse pointer, used to specify the host name belonging to an IP
4717 or IPv6 address. Name is stored plainly: 'www.powerdns.com'. As
4718 always, no terminating dot.
4722 Responsible Person record, as described in RFC 1183. Stored with a
4723 single space between the mailbox name and the more-information
4724 pointer. Example 'peter.powerdns.com peter.people.powerdns.com',
4725 to indicate that peter@powerdns.com is responsible and that more
4726 information about peter is available by querying the TXT record of
4727 peter.people.powerdns.com.
4731 The Start of Authority record is one of the most complex
4732 available. It specifies a lot about a domain: the name of the
4733 master nameserver ('the primary'), the hostmaster and a set of
4734 numbers indicating how the data in this domain expires and how
4735 often it needs to be checked. Further more, it contains a serial
4736 number which should rise on each change of the domain.
4738 The stored format is:
4740 primary hostmaster serial refresh retry expire default_ttl
4743 Besides the primary and the hostmaster, all fields are numerical.
4744 PDNS has a set of default values:
4746 Table 17-1. SOA fields
4748 +-----------------------------------------------------+
4749 | primary | default-soa-name configuration option |
4750 |-------------+---------------------------------------|
4751 | hostmaster | hostmaster@domain-name |
4752 |-------------+---------------------------------------|
4754 |-------------+---------------------------------------|
4755 | refresh | 10800 (3 hours) |
4756 |-------------+---------------------------------------|
4757 | retry | 3600 (1 hour) |
4758 |-------------+---------------------------------------|
4759 | expire | 604800 (1 week) |
4760 |-------------+---------------------------------------|
4761 | default_ttl | 3600 (1 hour) |
4762 +-----------------------------------------------------+
4764 The fields have complicated and sometimes controversial meanings.
4765 The 'serial' field is special. If left at 0, the default, PDNS
4766 will perform an internal list of the domain to determine highest
4767 change_date field of all records within the zone, and use that as
4768 the zone serial number. This means that the serial number is
4769 always raised when changes are made to the zone, as long as the
4770 change_date field is being set.
4774 SRV records can be used to encode the location and port of
4775 services on a domain name. When encoding, the priority field is
4776 used to encode the priority. For example,
4777 '_ldap._tcp.dc._msdcs.conaxis.ch SRV 0 100 389 mars.conaxis.ch'
4778 would be encoded with 0 in the priorit field and '100 389
4779 mars.conaxis.ch' in the tontent field.
4783 The TXT field can be used to attach textual data to a domain. Text
4786 ----------------------------------------------------------------------
4788 Chapter 18. HOWTO & Frequently Asked Questions
4790 This chapter contains a number of FAQs and HOWTOs.
4792 ----------------------------------------------------------------------
4794 18.1. Getting support, free and paid FAQ
4796 PowerDNS is an open source program so you may get help from the PowerDNS
4797 users' community or from its authors. You may also help others (please
4800 Some users may not have experience in interacting with developers or the
4801 open source community. This FAQ is to be considered MANDATORY READING
4802 before asking us for help.
4806 A: Please try harder. Specifically, before people will be able to
4807 help you, they need to know a lot about your system. Things you
4808 may find irrelevant. But, as you have a problem, you are not in a
4809 good position to know what is relevant and what not.
4811 Q: I have a question, what details should I supply?
4813 A: Start out with stating what you think should be happening.
4814 Quite often, wrong expectations are the actual proble.
4815 Furthermore, which database backend you use, your operating
4816 system, which version of PowerDNS you use and where you got it
4817 from (RPM, .DEB, tar.gz). If you compiled it yourself, what were
4818 the ./configure parameters.
4820 In the Open Source community, not supplying vital details is
4821 interpreted as a lack of respect for those willing to take time to
4822 answer your questions!
4824 If at *all* possible, supply the actual name of your domain and
4825 the IP address of your server(s).
4827 Q: Where should I send my question?
4829 A: To a mailinglist. Do not mail the authors directly unless you
4830 previously entered a support contract with them! For subscription
4831 details, see the mailinglists page.
4833 Questions about using PowerDNS should be sent to the pdns-users
4834 list, questions about compiler errors or feature requests to
4837 Before posting, read all FAQs and tell people you did.
4839 Q: I'm special, I don't email to mailinglists!
4841 We're special too, and we ask you to mail the mailinglists. If you
4842 need privacy, consider entering a support relationship with us, in
4843 which case you can email <support@powerdns.com>.
4845 ----------------------------------------------------------------------
4847 18.2. Using and Compiling PowerDNS FAQ
4849 In the course of compiling and using PowerDNS, many questions may arise.
4850 Here are some we've heard earlier or questions we expect people may have.
4851 Please read this list before mailing us!
4853 Q: I get this entry a lot of times in my log file: Authoritative empty NO
4854 ERROR to 1.2.3.4 for 'powerdns.nl' (AAAA)..
4856 As the name implies, this is not an error. It tells you there are
4857 questions for a domain which exists in your database, but for
4858 which no record of the requested type exists. To get rid of this
4859 error, add log-dns-details=off to your configuration.
4861 Q: Can I launch multiple backends simultaneously?
4863 A: You can. This might for example be useful to keep an existing
4864 BIND configuration around but to store new zones in, say MySQL.
4865 The syntax to use is 'launch=bind,gmysql'.
4867 Q: PowerDNS does not give authoritative answers, how come?
4869 A: This is almost always not the case. An authoritative answer is
4870 recognized by the 'AA' bit being set. Many tools prominently print
4871 the number of Authority records included in an answer, leading
4872 users to conclude that the absence or presence of these records
4873 indicates the authority of an answer. This is not the case.
4875 Verily, many misguided country code domain operators have fallen
4876 into this trap and demand authority records, even though these are
4877 fluff and quite often misleading. Invite such operators to look at
4878 section 6.2.1 of RFC 1034, which shows a correct authoritative
4879 answer without authority records. In fact, none of the
4880 non-deprecated authoritative answers shown have authority records!
4882 Sorry for sounding like DJB on this, but we get so many misguided
4883 questions about authority..
4885 Q: Which backend should I use? There are so many!
4887 A: If you have no external constraints, the Generic MySQL (gmysql)
4888 and Generic PostgreSQL (gpgsql) ones are probably the most used
4889 and complete. By all means do not use the non-generic MySQL
4890 backend, which is deprecated and only available for older
4893 The Oracle backend also has happy users, we know of no deployments
4894 of the DB2 backend. The BIND backend is pretty capable too in
4895 fact, but many prefer a relational database.
4897 Q: I try to launch the pgmysqlbackend and it can't find it!
4899 A: You did not read the changelog, nor the README. The 'pgmysql'
4900 backend is no more and has been split into the gmysql and gpgsql
4901 backends, with the common code residing within PowerDNS itself.
4903 Q: PowerDNS compiles under OpenBSD, but crashes immediately, now what?
4905 A: Reasons behind this are somewhat unclear but we hear they go
4906 away if you use a more recent compiler. Let us know on
4907 <pdns-dev@mailman.powerdns.com>. See also here.
4909 Q: I'm trying to build from CVS but I get lots of weird errors!
4911 A: Read the 'HACKING' file, it lists the build requirements
4912 (mostly autoconf, automake, libtool). In many cases, it may be
4913 easier to build from the source distribution though.
4915 Q: I'm on Solaris 7 and AAAA records do not work
4917 A: Indeed, and this is pretty sad. Either upgrade to Solaris 8 or
4918 convince people to write the replacement functions needed to
4919 encode AAAA if the host operating system does not offer them.
4921 Q: When compiling I get errors about 'sstream' and 'ostringstream', or
4924 A: Your gcc is too old. Versions 2.95.2 and older are not
4925 supported. Many distributions have improved gcc 2.95.2 with an
4926 ostringstream implementation, in which case their 2.95.2 is also
4927 supported. We like gcc 3.2.1 best.
4929 Q: Ok, I've installed gcc 3.2.1 but now the gpgsql backend won't link
4931 A: Sadly, the gcc C++ on-disk object format has changed a few
4932 times since the 2.95 days. This means that gcc 3.2.1 cannot link
4933 against libpq++.so compiled with 2.95. The trick is to recompile
4934 PostgreSQL with 3.2.1 too and have it install in a separate
4935 location. Then reconfigure the pdns compile to look there, with
4936 ./configure --with-pgsql-lib=/opt/postgresql-with-3.2.1/lib
4938 Q: I've installed PostgreSQL 7.3 but it has no libpq++.so
4940 A: As of 7.3, libpq++ has been split out of the main PostgreSQL
4941 distribution. See here. It would in fact be a great idea to move
4942 the gpgsql backend to the C interface instead of the C++ one. On
4943 Debian 'Sid', libpq++.so hides in the libpqpp-dev package.
4945 Q: PowerDNS crashes when I install the pdns-static .deb on Debian SID
4947 A: Indeed. Install the .debs that come with Debian or recompile
4948 PowerDNS yourself. If not using MySQL, the crashes will go away if
4949 you remove setuid and setgid statements from the configuration.
4951 Q: Why don't my slaves act on notifications and transfer my updated zone?
4953 A: Raise the serial number of your zone. In most backends, this is
4954 the first digit of the SOA contents field. If this number is lower
4955 to equal to that on a slave, it will not consider your zone
4958 Q: Master or Slave support is not working, PDNS is not picking up changes
4960 A: The Master/Slave apparatus is off by default. Turn it on by
4961 adding a slave and/or master statement to the configuration file.
4962 Also, check that the configured backend is master or slave
4965 Q: My masters won't allow PowerDNS to access zones as it is using the
4966 wrong local IP address
4968 A: Mark Bergsma contributed the query-local-address setting to
4969 tell PowerDNS which local IP address to use.
4971 Q: I compiled PowerDNS myself and I see weird problems, especially on SMP
4973 A: There are known issues between gcc <3.2 and PowerDNS on Linux
4974 SMP systems. The exact cause is not known but moving to our
4975 precompiled version always fixes the problems. If you compile
4976 yourself, use a recent gcc!
4978 Q: PowerDNS does not answer queries on all my IP addresses and I've
4979 ignored the warning I got about that at startup
4981 A: Please don't ignore what PowerDNS says to you. Furthermore,
4982 read Chapter 15 about the local-address setting, and use it to
4983 specify which IP addresses PowerDNS should listen on.
4985 Q: Can I use a MySQL database with the Windows version of PowerDNS?
4987 A: You can. MySQL support is supplied through the ODBC backend,
4988 which is compiled into the main binary. So if you want to use
4989 MySQL you can change the pdns.conf file, which is located in the
4990 PowerDNS for Windows directory, to use the correct ODBC data
4991 sources. If you don't know how to use ODBC with MySQL:
4993 * Download MyODBC from http://www.mysql.com/
4995 * Install the MySQL ODBC driver.
4997 Then you can follow the instructions located in Chapter 3. But
4998 instead of selecting the Microsoft Access Driver you select the
4999 MySQL ODBC Driver and configure it to use your MySQL database.
5001 Note For other databases for which an ODBC driver is
5002 available, the procedure is the same as this example.
5004 ----------------------------------------------------------------------
5006 18.3. Backend developer HOWTO
5008 Writing backends without access to the full PDNS source means that you
5009 need to write code that can be loaded by PDNS at runtime. This in turn
5010 means that you need to use the same compiler that we do. For linux, this
5011 is currently GCC 3.0.4, although any 3.0.x compiler is probably fine. In
5012 tests, even 3.1 works.
5014 For FreeBSD we use GCC 2.95.2.
5016 Furthermore, your pdns_server executable must be dynamically linked. The
5017 default .rpm PDNS contains a static binary so you need to retrieve the
5018 dynamic rpm or the dynamic tar.gz or the Debian unstable ('Woody') deb.
5019 FreeBSD dynamic releases are forthcoming.
5021 Q: Will PDNS drivers work with other PDNS versions than they were compiled
5024 A: 'Probably'. We make no guarantees. Efforts have been made to
5025 keep the interface between the backend and PDNS as thin as
5026 possible. For example, a backend compiled with the 1.99.11 backend
5027 development kit works with 1.99.10. But don't count on it. We will
5028 notify when we think an incompatible API change has occured but
5029 you are best off recompiling your driver for each new PDNS
5032 Q: What is in that DNSPacket * pointer passed to lookup!
5034 A: For reasons outlined above, you should treat that pointer as
5035 opaque and only access it via the getRemote() functions made
5036 available and documented above. The DNSPacket class changes a lot
5037 and this level of indirection allows for greater changes to be
5038 made without changing the API to the backend coder.
5040 Q: How is the PowerDNS Open Source Backend Development Kit licensed?
5042 A: MIT X11, a very liberal license permitting basically
5045 Q: Can I release the backend I wrote?
5047 A: Please do! If you tell us about it we will list you on our
5050 Q: Can I sell backends I wrote?
5052 A: You can. Again, if you tell us about them we will list your
5053 backend on the site. You can keep the source of your backend
5054 secret if you want, or you can share it with the world under any
5055 license of your chosing.
5057 Q: Will PowerDNS use my code in the PDNS distribution?
5059 A: If your license permits it and we like your backend, we sure
5060 will. If your license does not permit it but we like your backend
5061 anyway we may contact you.
5063 Q: My backend compiles but when I try to load it, it says 'undefined
5064 symbol: _Z13BackendMakersv'
5066 A: Your pdns_server binary is static and cannot load a backend
5067 driver at runtime. Get a dynamic version of pdns, or complain to
5068 pdns@powerdns.com if one isn't available. To check what kind of
5069 binary you have, execute 'file $(which pdns_server)'.
5071 Q: My backend compiles but when I try to load it, it says 'undefined
5072 symbol: BackendMakers__Fv'
5074 A: You compiled with the wrong GCC. Use GCC 3.x for Linux, 2.95.x
5075 for FreeBSD. You may want to change g++ to g++-3.0 in the
5076 Makefile, or change your path so that 3.x is used.
5078 Q: I downloaded a dynamic copy of pdns_server but it doesn't run, even
5081 A: Run 'ldd' on the pdns_server binary and figure out what
5082 libraries you are missing. Most likely you need to install gcc 3.0
5083 libraries, RedHat 7.1 and 7.2 have packages available, Debian
5084 installs these by default if you use the 'unstable deb' of PDNS.
5086 Q: What I want can't be done from a backend - I need the whole PDNS source
5088 A: If you require the source, please contact us
5089 (pdns@powerdns.com). All commercial licensees receive the source,
5090 for others we may grant exceptions.
5092 Q: What is this 'AhuException' I keep reading about?
5094 A: This name has historical reasons and has no significance.
5096 Q: I need a backend but I can't write it, can you help?
5098 A: Yes, we also do custom development. Contact us at
5101 ----------------------------------------------------------------------
5103 18.4. About PowerDNS.COM BV, 'the company'
5105 As of 25 November 2002, the PowerDNS nameserver and its modules are open
5106 source. This has led to a lot of questions on the future of both PowerDNS,
5107 the company and the products. This FAQ attempts to address these
5110 Q: Is PowerDNS 2.9 really open source? What license?
5112 A: PowerDNS 2.9 is licensed under the GNU General Public License
5113 version two, the same license that covers the Linux kernel.
5115 Q: Is the open source version crippled?
5117 A: It is not. Not a single byte has been omitted.
5119 Q: Is the nameserver abandoned?
5121 A: Far from it. In fact, we expect development to speed up now
5122 that we have joined the open source community.
5124 Q: Why is the nameserver now open source?
5126 A: In the current economic climate and also the way the Internet
5127 is built up right now, selling software is very hard. Most
5128 potential customers had never before bought a piece of software
5129 for their UNIX internet setup. Even though we know (from the
5130 recent survey) that nameserver operators love PowerDNS, their
5131 suggested price for it is in the $100 range.
5133 For us, it makes far more sense to open source PowerDNS than to
5134 ask $100 for it. It is expected that open sourcing PowerDNS will
5135 lead to far higher adoption rates. We hope that PowerDNS will soon
5136 be included in major Linux and UNIX distributions.
5138 Q: How does PowerDNS.COM BV expect to make money now that the nameserver
5141 A: In fact, we don't expect to in the near future. We also don't
5142 have a lot of expenses, basically some hosting and a few domain
5145 However, we are available for consulting work, for example to help
5146 a large registrar or registry migrate to PowerDNS, or to help
5147 integrate our software in existing provisioning systems.
5149 Furthermore, non-GPL licenses are available for those needing to
5150 do closed source modifications, or for customers uncomfortable
5151 with the GPL. This is much like what MySQL AB is doing now.
5153 In fact, their strategy is a lot like ours in general.
5155 Q: Can I buy support contracts for PowerDNS?
5157 Sure, to do so, please contact us at <sales@powerdns.com>
5159 Q: Will you accept patches? We've added a feature
5161 Probably - in general, it is best to discuss your intentions and
5162 needs on the <pdns-dev@mailman.powerdns.com> (subscribe)
5163 mailinglist before doing the work. We may have suggestions or
5164 guidelines on how you should implement the feature.
5166 Q: PowerDNS doesn't work on my platform, will you port it?, Q: PowerDNS
5167 doesn't have feature I need, will you add it?
5169 Be sure to ask on the <pdns-dev@mailman.powerdns.com> (subscribe)
5170 mailinglist. You can even hire us to do work on PowerDNS if plain
5171 asking is not persuasive enough. This might be the case if we
5172 don't currently have time for your feature, but you need it
5173 quickly anyhow, and are not in a position to submit a patch
5176 Q: Will PowerDNS Express be open sourced?
5178 Perhaps, we're not yet sure.
5180 Q: We are a Linux/Unix vendor, can we include PowerDNS?
5182 A: Please do. In fact, we'd be very happy to work with you to make
5183 this happen. Contact <ahu@ds9a.nl> if you have specific upstream
5186 ----------------------------------------------------------------------
5188 Appendix A. Backends in detail
5190 This appendix lists several of the available backends in more detail
5192 ----------------------------------------------------------------------
5196 Table A-1. PipeBackend capabilities
5198 +-----------------------+
5200 |-------------+---------|
5202 |-------------+---------|
5204 |-------------+---------|
5206 |-------------+---------|
5208 |-------------+---------|
5210 |-------------+---------|
5211 | Module name | pipe |
5212 |-------------+---------|
5213 | Launch name | pipe |
5214 +-----------------------+
5216 The PipeBackend allows for easy dynamic resolution based on a 'Coprocess'
5217 which can be written in any programming language that can read a question
5218 on standard input and answer on standard output.
5220 Note The Pipe Backend currently does not function under FreeBSD 4.x and
5221 5.x, probably due to unfavorable interactions between its threading
5222 implementation and the fork system call.
5224 Interestingly, the Linux PowerDNS binary running under the
5225 Linuxulator on FreeBSD does work.
5227 To configure, the following settings are available:
5231 Command to launch as backend. Mandatory.
5235 Number of milliseconds to wait for an answer from the backend. If
5236 this time is ever exceeded, the backend is declared dead and a new
5237 process is spawned. Available since 2.7.
5241 If set, only questions matching this regular expression are even
5242 sent to the backend. This makes sure that most of PowerDNS does
5243 not slow down if you you reploy a slow backend. A query for the A
5244 record of 'www.powerdns.com' would be presented to the regex as
5245 'www.powerdns.com;A'. A matching regex would be
5246 '^www.powerdns.com;.*$'.
5248 To match only ANY and A queries for www.powerdns.com, use
5249 '^www.powerdns.com;(A|ANY)$'. Available since 2.8.
5251 ----------------------------------------------------------------------
5253 A.1.1. PipeBackend protocol
5255 Questions come in over a file descriptor, by default standard input.
5256 Answers are sent out over another file descriptor, standard output by
5259 ----------------------------------------------------------------------
5263 PowerDNS sends out 'HELO\t1', indicating that it wants to speak the
5264 protocol as defined in this document, version 1. A PowerDNS CoProcess must
5265 then send out a banner, prefixed by 'OK\t', indicating it launched
5266 successfully. If it does not support the indicated version, it should
5267 respond with FAIL, but not exit. Suggested behaviour is to try and read a
5268 further line, and wait to be terminated.
5270 ----------------------------------------------------------------------
5274 Questions come in three forms and are prefixed by a tag indicating the
5283 List requests, which mean that an entire zone should be listed
5287 Check if the coprocess is functioning
5289 The question format:
5291 type qname qclass qtype id ip-address
5293 Fields are tab separated, and terminated with a single \n. Type is the tag
5294 above, qname is the domain the question is about. qclass is always 'IN'
5295 currently, denoting an INternet question. qtype is the kind of information
5296 desired, the record type, like A, CNAME or AAAA. id can be specified to
5297 help your backend find an answer if the id is already known from an
5298 earlier query. You can ignore it. ip-address is the ip-address of the
5299 nameserver asking the question.
5301 ----------------------------------------------------------------------
5305 \r Each answer starts with a tag, possibly followed by a TAB and more data.
5309 Indicating a successful line of DATA
5313 Indicating the end of an answer - no further data
5317 Indicating a lookup failure. Also serves as 'END'. No further
5322 For specifying things that should be logged. Can only be sent
5323 after a query and before an END line. After the tab, the message
5326 So letting it be known that there is no data consists if sending 'END'
5327 without anything else. The answer format:
5329 DATA qname qclass qtype ttl id content
5331 'content' is as specified in Chapter 17. A sample dialogue may look like
5334 Q www.ds9a.nl IN CNAME -1 213.244.168.210
5335 DATA www.ds9a.nl IN CNAME 3600 1 ws1.ds9a.nl
5336 Q ws1.ds9a.nl IN CNAME -1 213.244.168.210
5338 Q wd1.ds9a.nl IN A -1 213.244.168.210
5339 DATA ws1.ds9a.nl IN A 3600 1 1.2.3.4
5340 DATA ws1.ds9a.nl IN A 3600 1 1.2.3.5
5341 DATA ws1.ds9a.nl IN A 3600 1 1.2.3.6
5344 This would correspond to a remote webserver 213.244.168.210 wanting to
5345 resolve the IP address of www.ds9a.nl, and PowerDNS traversing the CNAMEs
5346 to find the IP addresses of ws1.ds9a.nl Another dialogue might be:
5348 Q ds9a.nl IN SOA -1 213.244.168.210
5349 DATA ds9a.nl IN SOA 86400 1 ahu.ds9a.nl ...
5352 DATA ds9a.nl IN SOA 86400 1 ahu.ds9a.nl ...
5353 DATA ds9a.nl IN NS 86400 1 ns1.ds9a.nl
5354 DATA ds9a.nl IN NS 86400 1 ns2.ds9a.nl
5355 DATA ns1.ds9a.nl IN A 86400 1 213.244.168.210
5356 DATA ns2.ds9a.nl IN A 86400 1 63.123.33.135
5361 This is a typical zone transfer.
5363 ----------------------------------------------------------------------
5365 A.1.1.4. Sample perl backend
5368 # sample PowerDNS Coprocess backend
5374 $|=1; # no buffering
5379 unless($line eq "HELO\t1") {
5381 print STDERR "Recevied '$line'\n";
5385 print "OK Sample backend firing up\n"; # print our banner
5389 print STDERR "$$ Received: $_";
5391 my @arr=split(/\t/);
5393 print "LOG PowerDNS sent unparseable line\n";
5398 my ($type,$qname,$qclass,$qtype,$id,$ip)=split(/\t/);
5400 if(($qtype eq "A" || $qtype eq "ANY") && $qname eq "webserver.example.com") {
5401 print STDERR "$$ Sent A records\n";
5402 print "DATA $qname $qclass A 3600 -1 1.2.3.4\n";
5403 print "DATA $qname $qclass A 3600 -1 1.2.3.5\n";
5404 print "DATA $qname $qclass A 3600 -1 1.2.3.6\n";
5406 elsif(($qtype eq "CNAME" || $qtype eq "ANY") && $qname eq "www.example.com") {
5407 print STDERR "$$ Sent CNAME records\n";
5408 print "DATA $qname $qclass CNAME 3600 -1 webserver.example.com\n";
5410 elsif($qtype eq "MBOXFW") {
5411 print STDERR "$$ Sent MBOXFW records\n";
5412 print "DATA $qname $qclass MBOXFW 3600 -1 powerdns\@example.com\n";
5416 print STDERR "$$ End of data\n";
5421 ----------------------------------------------------------------------
5425 Warning This backend is deprecated! Use the Generic MySQL backend which is
5426 better in all respects. It does support master/slave operation,
5427 this backend does not. See Section A.5.
5429 So stop reading here unless you already have a database filled
5430 with 'mysql' records.
5432 Table A-2. MySQL backend capabilities
5434 +---------------------------+
5436 |-------------+-------------|
5438 |-------------+-------------|
5440 |-------------+-------------|
5442 |-------------+-------------|
5443 | Autoserial | Yes |
5444 |-------------+-------------|
5445 | Case | Insensitive |
5446 |-------------+-------------|
5447 | Module name | mysql |
5448 |-------------+-------------|
5449 | Launch name | mysql |
5450 +---------------------------+
5452 The MySQL Backend as present in PDNS is fixed - it requires a certain
5453 database schema to function. This schema corresponds to this create
5456 CREATE TABLE records (
5457 id int(11) NOT NULL auto_increment,
5458 domain_id int(11) NOT NULL,
5459 name varchar(255) NOT NULL,
5460 type varchar(6) NOT NULL,
5461 content varchar(255) NOT NULL,
5462 ttl int(11) NOT NULL,
5463 prio int(11) default NULL,
5464 change_date int(11) default NULL,
5466 KEY name_index(name),
5467 KEY nametype_index(name,type),
5468 KEY domainid_index(domain_id)
5472 Every domain should have a unique domain_id, which should remain identical
5473 for all records in a domain. Records with a domain_id that differs from
5474 that in the domain SOA record will not appear in a zone transfer.
5476 The change_date may optionally be updated to the time_t (the number of
5477 seconds since midnight UTC at the start of 1970), and is in that case used
5478 to auto calculate the SOA serial number in case that is unspecified.
5480 ----------------------------------------------------------------------
5482 A.2.1. Configuration settings
5484 WARNING! Make sure that you can actually resolve the hostname of your
5485 database without accessing the database! It is advised to supply an IP
5486 address here to prevent chicken/egg problems!
5490 Database name to connect to
5494 Database host to connect to
5498 Password to connect with
5502 MySQL socket to use for connecting
5506 MySQL table name. Defaults to 'records'.
5510 MySQL user to connect as
5512 ----------------------------------------------------------------------
5516 It has been observed that InnoDB tables outperform the default MyISAM
5517 tables by a large margin. Furthermore, the default number of backends (3)
5518 should be raised to 10 or 15 for busy servers.
5520 ----------------------------------------------------------------------
5524 Table A-3. Random Backend capabilities
5526 +------------------------+
5528 |-------------+----------|
5530 |-------------+----------|
5532 |-------------+----------|
5534 |-------------+----------|
5536 |-------------+----------|
5538 |-------------+----------|
5539 | Module name | built in |
5540 |-------------+----------|
5541 | Lauch name | random |
5542 +------------------------+
5544 This is a very silly backend which is discussed in Section C.1 as a
5545 demonstration on how to write a PowerDNS backend.
5547 This backend knows about only one hostname, and only about its IP address
5548 at that. With every query, a new random IP address is generated.
5550 It only makes sense to load the random backend in combination with a
5551 regular backend. This can be done by prepending it to the launch=
5552 instruction, such as launch=random,gmysql.
5558 Hostname for which to supply a random IP address.
5560 ----------------------------------------------------------------------
5562 A.4. MySQL PDNS backend
5564 Table A-4. MySQL backend capabilities
5566 +---------------------------+
5568 |-------------+-------------|
5570 |-------------+-------------|
5572 |-------------+-------------|
5574 |-------------+-------------|
5575 | Autoserial | Yes |
5576 |-------------+-------------|
5577 | Case | Insensitive |
5578 |-------------+-------------|
5579 | Module name | pdns |
5580 |-------------+-------------|
5581 | Lauch name | pdns |
5582 +---------------------------+
5584 This is the driver that corresponds to the set of XML-RPC tools available
5589 CREATE TABLE MailForwards (
5590 Id int(10) unsigned NOT NULL auto_increment,
5591 ZoneId int(10) unsigned NOT NULL default '0',
5592 Name varchar(255) NOT NULL default '',
5593 Destination varchar(255) NOT NULL default '',
5594 Flags int(11) NOT NULL default '0',
5595 ChangeDate timestamp(14) NOT NULL,
5596 CreateDate timestamp(14) NOT NULL,
5597 Active tinyint(4) NOT NULL default '0',
5599 KEY NameIndex (Name),
5600 KEY ZoneIdIndex (ZoneId)
5604 -- Table structure for table 'Mailboxes'
5607 CREATE TABLE Mailboxes (
5608 Id int(10) unsigned NOT NULL auto_increment,
5609 ZoneId int(10) unsigned NOT NULL default '0',
5610 Name varchar(255) NOT NULL default '',
5611 Password varchar(255) NOT NULL default '',
5612 Quota int(10) unsigned NOT NULL default '0',
5613 Flags int(11) NOT NULL default '0',
5614 ChangeDate timestamp(14) NOT NULL,
5615 CreateDate timestamp(14) NOT NULL,
5616 Active tinyint(4) NOT NULL default '0',
5618 UNIQUE KEY Name (Name),
5619 KEY ZoneIdIndex (ZoneId),
5620 KEY NameIndex (Name)
5624 -- Table structure for table 'Records'
5627 CREATE TABLE Records (
5628 Id int(10) unsigned NOT NULL auto_increment,
5629 ZoneId int(10) unsigned NOT NULL default '0',
5630 Name varchar(255) NOT NULL default '',
5631 Type varchar(8) NOT NULL default '',
5632 Content varchar(255) NOT NULL default '',
5633 TimeToLive int(11) NOT NULL default '60',
5634 Priority int(11) NOT NULL default '0',
5635 Flags int(11) NOT NULL default '0',
5636 ChangeDate timestamp(14) NOT NULL,
5637 CreateDate timestamp(14) NOT NULL,
5638 Active tinyint(4) NOT NULL default '0',
5640 KEY NameIndex (Name)
5644 -- Table structure for table 'WebForwards'
5647 CREATE TABLE WebForwards (
5648 Id int(10) unsigned NOT NULL auto_increment,
5649 ZoneId int(10) unsigned NOT NULL default '0',
5650 Name varchar(255) NOT NULL default '',
5651 Destination varchar(255) NOT NULL default '',
5652 Type varchar(7) NOT NULL default 'NORMAL',
5653 Title varchar(255) NOT NULL default '',
5654 Description varchar(255) NOT NULL default '',
5655 Keywords varchar(255) NOT NULL default '',
5656 FavIcon varchar(255) NOT NULL default '',
5657 Flags int(11) NOT NULL default '0',
5658 ChangeDate timestamp(14) NOT NULL,
5659 CreateDate timestamp(14) NOT NULL,
5660 Active tinyint(4) NOT NULL default '0',
5662 KEY NameIndex (Name),
5663 KEY ZoneIdIndex (ZoneId)
5667 -- Table structure for table 'Zones'
5670 CREATE TABLE Zones (
5671 Id int(10) unsigned NOT NULL auto_increment,
5672 Name varchar(255) NOT NULL default '',
5673 Hostmaster varchar(255) NOT NULL default '',
5674 Serial int(10) unsigned NOT NULL default '0',
5675 AutoSerial tinyint(4) NOT NULL default '0',
5676 Flags int(11) NOT NULL default '0',
5677 ChangeDate timestamp(14) NOT NULL,
5678 CreateDate timestamp(14) NOT NULL,
5679 Active tinyint(4) NOT NULL default '0',
5680 TimeToLive int(11) NOT NULL default '0',
5681 OwnerId varchar(255) NOT NULL default '',
5683 UNIQUE KEY Name (Name),
5684 KEY NameIndex (Name)
5689 It takes a number of parameters:
5693 Database name to connect to
5697 Database host to connect to
5701 Password to connect with
5705 MySQL socket to use for connecting
5709 MySQL user to connect as
5711 ----------------------------------------------------------------------
5715 It has been observed that InnoDB tables outperform the default MyISAM
5716 tables by a large margin. Furthermore, the default number of backends (3)
5717 should be raised to 10 or 15 for busy servers.
5719 ----------------------------------------------------------------------
5721 A.5. Generic MySQL and PgSQL backends
5723 Table A-5. Generic PgSQL and MySQL backend capabilities
5725 +---------------------------------------------------------------+
5726 | Native | Yes - but PostgreSQL does not replicate |
5727 |---------------------+-----------------------------------------|
5729 |---------------------+-----------------------------------------|
5731 |---------------------+-----------------------------------------|
5732 | Superslave | Yes |
5733 |---------------------+-----------------------------------------|
5735 |---------------------+-----------------------------------------|
5736 | Case | All lower |
5737 |---------------------+-----------------------------------------|
5738 | Module name < 2.9.3 | pgmysql |
5739 |---------------------+-----------------------------------------|
5740 | Module name > 2.9.2 | gmysql and gpgsql |
5741 |---------------------+-----------------------------------------|
5742 | Lauch name | gmysql and gpgsql2 and gpgsql |
5743 +---------------------------------------------------------------+
5745 PostgreSQL and MySQL backend with easily configurable SQL statements,
5746 allowing you to graft PDNS on any PostgreSQL or MySQL database of your
5747 choosing. Because all database schemas will be different, a generic
5748 backend is needed to cover all needs.
5750 The template queries are expanded using the C function 'snprintf' which
5751 implies that substitutions are performed on the basis of %-place holders.
5752 To place a a % in a query which will not be substituted, use %%. Make sure
5753 to fill out the search key, often called 'name' in lower case!
5755 There are in fact two backends, one for PostgreSQL and one for MySQL but
5756 they accept the same settings and use almost exactly the same database
5759 ----------------------------------------------------------------------
5761 A.5.1. MySQL specifics
5763 Warning If using MySQL with 'slave' support enabled in PowerDNS you must
5764 run MySQL with a table engine that supports transactions.
5766 In practice, great results are achieved with the 'InnoDB' tables. PowerDNS
5767 will silently function with non-transaction aware MySQLs but at one point
5768 this is going to harm your database, for example when an incoming zone
5771 The default setup conforms to the following schema:
5773 create table domains (
5774 id INT auto_increment,
5775 name VARCHAR(255) NOT NULL,
5776 master VARCHAR(20) DEFAULT NULL,
5777 last_check INT DEFAULT NULL,
5778 type VARCHAR(6) NOT NULL,
5779 notified_serial INT DEFAULT NULL,
5780 account VARCHAR(40) DEFAULT NULL,
5784 CREATE UNIQUE INDEX name_index ON domains(name);
5786 CREATE TABLE records (
5787 id INT auto_increment,
5788 domain_id INT DEFAULT NULL,
5789 name VARCHAR(255) DEFAULT NULL,
5790 type VARCHAR(6) DEFAULT NULL,
5791 content VARCHAR(255) DEFAULT NULL,
5792 ttl INT DEFAULT NULL,
5793 prio INT DEFAULT NULL,
5794 change_date INT DEFAULT NULL,
5798 CREATE INDEX rec_name_index ON records(name);
5799 CREATE INDEX nametype_index ON records(name,type);
5800 CREATE INDEX domain_id ON records(domain_id);
5802 create table supermasters (
5803 ip VARCHAR(25) NOT NULL,
5804 nameserver VARCHAR(255) NOT NULL,
5805 account VARCHAR(40) DEFAULT NULL
5808 GRANT SELECT ON supermasters TO pdns;
5809 GRANT ALL ON domains TO pdns;
5810 GRANT ALL ON records TO pdns;
5813 This schema contains all elements needed for master, slave and superslave
5814 operation. Depending on which features will be used, the 'GRANT'
5815 statements can be trimmed to make sure PDNS cannot subvert the contents of
5818 Zone2sql with the --gmysql flag also assumes this layout is in place.
5820 ----------------------------------------------------------------------
5822 A.5.2. PostgresSQL specifics
5824 The default setup conforms to the following schema, which you should add
5825 to a PostgreSQL database.
5827 create table domains (
5828 id SERIAL PRIMARY KEY,
5829 name VARCHAR(255) NOT NULL,
5830 master VARCHAR(20) DEFAULT NULL,
5831 last_check INT DEFAULT NULL,
5832 type VARCHAR(6) NOT NULL,
5833 notified_serial INT DEFAULT NULL,
5834 account VARCHAR(40) DEFAULT NULL
5836 CREATE UNIQUE INDEX name_index ON domains(name);
5838 CREATE TABLE records (
5839 id SERIAL PRIMARY KEY,
5840 domain_id INT DEFAULT NULL,
5841 name VARCHAR(255) DEFAULT NULL,
5842 type VARCHAR(6) DEFAULT NULL,
5843 content VARCHAR(255) DEFAULT NULL,
5844 ttl INT DEFAULT NULL,
5845 prio INT DEFAULT NULL,
5846 change_date INT DEFAULT NULL,
5847 CONSTRAINT domain_exists
5848 FOREIGN KEY(domain_id) REFERENCES domains(id)
5852 CREATE INDEX rec_name_index ON records(name);
5853 CREATE INDEX nametype_index ON records(name,type);
5854 CREATE INDEX domain_id ON records(domain_id);
5856 create table supermasters (
5857 ip VARCHAR(25) NOT NULL,
5858 nameserver VARCHAR(255) NOT NULL,
5859 account VARCHAR(40) DEFAULT NULL
5862 GRANT SELECT ON supermasters TO pdns;
5863 GRANT ALL ON domains TO pdns;
5864 GRANT ALL ON domains_id_seq TO pdns;
5865 GRANT ALL ON records TO pdns;
5866 GRANT ALL ON records_id_seq TO pdns;
5869 This schema contains all elements needed for master, slave and superslave
5870 operation. Depending on which features will be used, the 'GRANT'
5871 statements can be trimmed to make sure PDNS cannot subvert the contents of
5874 Zone2sql with the --gpgsql flag also assumes this layout is in place.
5876 With PostgreSQL, you may have to run 'createdb powerdns' first and then
5877 connect to that database with 'psql powerdns', and feed it the schema
5880 ----------------------------------------------------------------------
5882 A.5.3. Basic functionality
5884 4 queries are needed for regular lookups, 4 for 'fancy records' which are
5885 disabled by default and 1 is needed for zone transfers.
5887 The 4+4 regular queries must return the following 6 fields, in this exact
5892 This is the 'right hand side' of a DNS record. For an A record,
5893 this is the IP address for example.
5897 TTL of this record, in seconds. Must be a real value, no checking
5902 For MX records, this should be the priority of the mail exchanger
5907 The ASCII representation of the qtype of this record. Examples are
5908 'A', 'MX', 'SOA', 'AAAA'. Make sure that this field returns an
5909 exact answer - PDNS won't recognise 'A ' as 'A'. This can be
5910 achieved by using a VARCHAR instead of a CHAR.
5914 Each domain must have a unique domain_id. No two domains may share
5915 a domain_id, all records in a domain should have the same. A
5920 Actual name of a record. Must not end in a '.' and be fully
5921 qualified - it is not relative to the name of the domain!
5923 Please note that the names of the fields are not relevant, but the order
5926 As said earlier, there are 8 SQL queries for regular lookups. To configure
5927 them, set 'gmysql-basic-query' or 'gpgsql-basic-query', depending on your
5928 choice of backend. If so called 'MBOXFW' fancy records are not used, four
5933 Default: select content,ttl,prio,type,domain_id,name from records
5934 where qtype='%s' and name='%s' This is the most used query, needed
5935 for doing 1:1 lookups of qtype/name values. First %s is replaced
5936 by the ASCII representation of the qtype of the question, the
5941 Default: select content,ttl,prio,type,domain_id,name from records
5942 where qtype='%s' and name='%s' and domain_id=%d Used for doing
5943 lookups within a domain. First %s is replaced by the qtype, the %d
5944 which should appear after the %s by the numeric domain_id.
5948 For doing ANY queries. Also used internally. Default: select
5949 content,ttl,prio,type,domain_id,name from records where name='%s'
5950 The %s is replaced by the qname of the question.
5954 For doing ANY queries within a domain. Also used internally.
5955 Default: select content,ttl,prio,type,domain_id,name from records
5956 where name='%s' and domain_id=%d The %s is replaced by the name of
5957 the domain, the %d by the numerical domain id.
5959 The last query is for listing the entire contents of a zone. This is
5960 needed when performing a zone transfer, but sometimes also internally:
5964 To list an entire zone. Default: select
5965 content,ttl,prio,type,domain_id,name from records where
5968 ----------------------------------------------------------------------
5970 A.5.4. Master/slave queries
5972 Most installations will have zero need to change the following settings,
5973 but should the need arise, here they are:
5977 Called to determine the master of a zone. Default: select master
5978 from domains where name='%s' and type='SLAVE'
5982 Called to retrieve (nearly) all information for a domain: Default:
5983 select id,name,master,last_check,notified_serial,type from domains
5986 info-all-slaves-query
5988 Called to retrieve all slave domains Default: select
5989 id,name,master,last_check,type from domains where type='SLAVE'
5993 Called to determine if a certain host is a supermaster for a
5994 certain domain name. Default: select account from supermasters
5995 where ip='%s' and nameserver='%s'");
5999 Called to add a domain as slave after a supermaster notification.
6000 Default: insert into domains (type,name,master,account)
6001 values('SLAVE','%s','%s','%s')
6005 Called during incoming AXFR. Default: insert into records
6006 (content,ttl,prio,type,domain_id,name) values
6007 ('%s',%d,%d,'%s',%d,'%s')
6011 Called to update the last notified serial of a master domain.
6012 Default: update domains set notified_serial=%d where id=%d
6014 update-lastcheck-query
6016 Called to update the last time a slave domain was checked for
6017 freshness. Default: update domains set notified_serial=%d where
6020 info-all-master-query
6022 Called to get data on all domains for which the server is master.
6023 Default: select id,name,master,last_check,notified_serial,type
6024 from domains where type='MASTER'
6028 Called to delete all records of a zone. Used before an incoming
6029 AXFR. Default: delete from records where domain_id=%d
6031 ----------------------------------------------------------------------
6033 A.5.5. Fancy records
6035 If PDNS is used with so called 'Fancy Records', the 'MBOXFW' record exists
6036 which specifies an email address forwarding instruction, wildcard queries
6037 are sometimes needed. This is not enabled by default. A wildcard query is
6038 an internal concept - it has no relation to *.domain-type lookups. You can
6039 safely leave these queries blank.
6043 Can be left blank. See above for an explanation. Default: select
6044 content,ttl,prio,type,domain_id,name from records where qtype='%s'
6049 Can be left blank. See above for an explanation. Default: select
6050 content,ttl,prio,type,domain_id,name from records where qtype='%s'
6051 and name like '%s' and domain_id=%d Used for doing lookups within
6056 For doing wildcard ANY queries. Default: select
6057 content,ttl,prio,type,domain_id,name from records where name like
6060 wildcard-any-id-query
6062 For doing wildcard ANY queries within a domain. Default: select
6063 content,ttl,prio,type,domain_id,name from records where name like
6064 '%s' and domain_id=%d
6066 ----------------------------------------------------------------------
6068 A.5.6. Settings and specifying queries
6070 The queries above are specified in pdns.conf. For example, the basic-query
6073 gpgsql-basic-query=select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name='%s'
6076 When using the Generic PostgreSQL backend, they appear as above. When
6077 using the generic MySQL backend, change the "gpgsql-" prefix to "gmysql-".
6079 Queries can span multiple lines, like this:
6081 gpgsql-basic-query=select content,ttl,prio,type,domain_id,name from records \
6082 where qtype='%s' and name='%s'
6085 Do not wrap statements in quotes as this will not work. Besides the query
6086 related settings, the following configuration options are available:
6090 Database name to connect to
6094 Database host to connect to. WARNING: When specified as a hostname
6095 a chicken/egg situation might arise where the database is needed
6096 to resolve the IP address of the database. It is best to supply an
6097 IP address of the database here.
6099 gmysql-socket (only for MySQL!)
6101 Filename where the MySQL connection socket resides. Often
6102 /tmp/mysql.sock or /var/run/mysqld/mysqld.sock.
6106 Password to connect with
6110 PgSQL user to connect as
6112 ----------------------------------------------------------------------
6114 A.5.7. Native operation
6116 For native operation, either drop the FOREIGN KEY on the domain_id field,
6117 or (recommended), make sure the domains table is filled properly. To add a
6118 domain, issue the following:
6120 insert into domains (name,type) values ('powerdns.com','NATIVE');
6123 The records table can now be filled by with the domain_id set to the id of
6124 the domains table row just inserted.
6126 ----------------------------------------------------------------------
6128 A.5.8. Slave operation
6130 The PostgreSQL backend is fully slave capable. To become a slave of the
6131 'powerdns.com' domain, execute this:
6133 insert into domains (name,master,type) values ('powerdns.com','213.244.168.217','SLAVE');
6136 And wait a while for PDNS to pick up the addition - which happens within
6137 one minute. There is no need to inform PDNS that a new domain was added.
6140 Apr 09 13:34:29 All slave domains are fresh
6141 Apr 09 13:35:29 1 slave domain needs checking
6142 Apr 09 13:35:29 Domain powerdns.com is stale, master serial 1, our serial 0
6143 Apr 09 13:35:30 [gPgSQLBackend] Connected to database
6144 Apr 09 13:35:30 AXFR started for 'powerdns.com'
6145 Apr 09 13:35:30 AXFR done for 'powerdns.com'
6146 Apr 09 13:35:30 [gPgSQLBackend] Closing connection
6149 From now on, PDNS is authoritative for the 'powerdns.com' zone and will
6150 respond accordingly for queries within that zone.
6152 Periodically, PDNS schedules checks to see if domains are still fresh. The
6153 default slave-cycle-interval is 60 seconds, large installations may need
6154 to raise this value. Once a domain has been checked, it will not be
6155 checked before its SOA refresh timer has expired. Domains whose status is
6156 unknown get checked every 60 seconds by default.
6158 ----------------------------------------------------------------------
6160 A.5.9. Superslave operation
6162 To configure a supermaster with IP address 10.0.0.11 which lists this
6163 installation as 'autoslave.powerdns.com', issue the following:
6165 insert into supermasters ('10.0.0.11','autoslave.powerdns.com','internal');
6168 From now on, valid notifies from 10.0.0.11 that list a NS record
6169 containing 'autoslave.powerdns.com' will lead to the provisioning of a
6170 slave domain under the account 'internal'. See Section 13.2.1 for details.
6172 ----------------------------------------------------------------------
6174 A.5.10. Master operation
6176 The PostgreSQL backend is fully master capable with automatic discovery of
6177 serial changes. Raising the serial number of a domain suffices to trigger
6178 PDNS to send out notifications. To configure a domain for master operation
6179 instead of the default native replication, issue:
6181 insert into domains (name,type) values ('powerdns.com','MASTER');
6184 Make sure that the assigned id in the domains table matches the domain_id
6185 field in the records table!
6187 ----------------------------------------------------------------------
6189 A.6. Generic Oracle backend
6191 Table A-6. Oracle backend capabilities
6193 +----------------------+
6195 |-------------+--------|
6197 |-------------+--------|
6199 |-------------+--------|
6201 |-------------+--------|
6202 | Autoserial | Yes |
6203 |-------------+--------|
6204 | Module name | oracle |
6205 |-------------+--------|
6206 | Launch name | oracle |
6207 +----------------------+
6209 Oracle backend with easily configurable SQL statements, allowing you to
6210 graft PDNS on any Oracle database of your choosing.
6212 PowerDNS is currently ascertaining if this backend can be distributed in
6213 binary form without violating Oracle licensing. In the meantime, the
6214 source code to the Oracle backend is available in the pdns distribution.
6216 The following configuration settings are available:
6218 oracle-debug-queries
6220 Output all queries to disk for debugging purposes.
6224 Output all queries to disk for timing purposes.
6226 oracle-uppercase-database
6228 Change all domain names to uppercase before querying database.
6232 Oracle database name to connect to.
6236 PDNS can set the ORACLE_HOME environment variable from within the
6237 executable, allowing execution of the daemon from init.d scripts
6238 where ORACLE_HOME may not yet be set.
6242 PDNS can set the ORACLE_SID environment variable from within the
6243 executable, allowing execution of the daemon from init.d scripts
6244 where ORACLE_SID may not yet be set.
6248 Oracle username to connect as.
6252 Oracle password to connect with.
6254 The generic Oracle backend can be configured to use user-specified
6255 queries. The following are the default queries and their names:
6257 oracle-forward-query
6259 select content, TimeToLive, Priority, type, ZoneId,
6260 nvl(ChangeDate,0) from Records where name = :name and type = :type
6262 oracle-forward-query-by-zone
6264 select content, TimeToLive, Priority, type, ZoneId,
6265 nvl(ChangeDate,0) from records where name = :name and type = :type
6268 oracle-forward-any-query
6270 select content, TimeToLive, Priority, type, ZoneId,
6271 nvl(ChangeDate,0) from records where name = :name
6275 select content, TimeToLive, Priority, type, ZoneId,
6276 nvl(ChangeDate, 0), name from records where ZoneId = :id
6278 ----------------------------------------------------------------------
6280 A.6.1. Setting up Oracle for use with PowerDNS
6282 To setup a database that corresponds to these default queries, issue the
6283 following as Oracle user sys:
6285 create user powerdns identified by YOURPASSWORD;
6286 grant connect to powerdns;
6288 create tablespace powerdns datafile '/opt/oracle/oradata/oracle/powerdns.dbf'
6289 size 256M extent management local autoallocate;
6291 alter user powerdns quota unlimited on powerdns;
6294 As user 'powerdns' continue with:
6296 create table Domains (
6297 ID number(11) NOT NULL,
6298 NAME VARCHAR(255) NOT NULL,
6299 MASTER VARCHAR(20) DEFAULT NULL,
6300 LAST_CHECK INT DEFAULT NULL,
6301 TYPE VARCHAR(6) NOT NULL,
6302 NOTIFIED_SERIAL INT DEFAULT NULL,
6303 ACCOUNT VARCHAR(40) DEFAULT NULL,
6305 )tablespace POWERDNS;
6307 create index DOMAINS$NAME on Domains (NAME) tablespace POWERDNS;
6308 create sequence DOMAINS_ID_SEQUENCE;
6310 create table Records
6312 ID number(11) NOT NULL,
6313 ZoneID number(11) default NULL REFERENCES Domains(ID) ON DELETE CASCADE,
6314 NAME varchar2(255) default NULL,
6315 TYPE varchar2(6) default NULL,
6316 CONTENT varchar2(255) default NULL,
6317 TimeToLive number(11) default NULL,
6318 Priority number(11) default NULL,
6319 CreateDate number(11) default NULL,
6320 ChangeDate number(11) default NULL,
6322 )tablespace POWERDNS;
6324 create index RECORDS$NAME on RECORDS (NAME) tablespace POWERDNS;
6325 create sequence RECORDS_ID_SEQUENCE;
6328 To insert records, either use zone2sql with the --oracle setting, or
6329 execute sql along the lines of:
6331 insert into domains (id,name,type) values (domains_id_sequence.nextval,'netherlabs.nl','NATIVE');
6332 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'SOA', 'ahu.casema.net. hostmaster.ds9a.nl. 2000081401 28800 7200 604800 86400', 3600, 0 from Domains where name='netherlabs.nl';
6333 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'NS', 'ahu.casema.net', 3600, 0 from Domains where name='netherlabs.nl';
6334 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'NS', 'ns1.pine.nl', 3600, 0 from Domains where name='netherlabs.nl';
6335 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'NS', 'ns2.pine.nl', 3600, 0 from Domains where name='netherlabs.nl';
6336 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'A', '213.244.168.210', 3600, 0 from Domains where name='netherlabs.nl';
6337 insert into Records (id,ZoneId, name,type,content,TimeToLive,Priority) select RECORDS_ID_SEQUENCE.nextval,id ,'netherlabs.nl', 'MX', 'outpost.ds9a.nl', 3600, 10 from Domains where name='netherlabs.nl';
6341 For performance reasons it is best to specify --transactions too!
6343 ----------------------------------------------------------------------
6345 A.7. Generic SQLite backend
6347 Table A-7. Generic SQLite backend capabilities
6349 +-----------------------+
6351 |-------------+---------|
6353 |-------------+---------|
6355 |-------------+---------|
6356 | Superslave | Yes |
6357 |-------------+---------|
6358 | Module name | gsqlite |
6359 |-------------+---------|
6360 | Launch name | gsqlite |
6361 +-----------------------+
6363 This backend retrieves all data from a SQLite database, which is a RDBMS
6364 that's embedded into the application itself, so you won't need to be
6365 running a seperate server process. It also reduces overhead, and
6366 simplifies installation. At http://www.sqlite.org you can find more
6367 information about SQLite.
6369 As this is a generic backend, built on top of the gSql framework, you can
6370 specify all queries as documented in Generic MySQL and PgSQL backends.
6372 ----------------------------------------------------------------------
6374 A.7.1. Compiling the SQLite backend
6376 Before you can begin compiling PowerDNS with the SQLite backend you need
6377 to have the SQLite utility and library installed on your system. You can
6378 download these from http://www.sqlite.org/download.html, or you can use
6379 packages (if your distribution provides those).
6381 When you've installed the library you can use: ./configure
6382 --with-modules="gsqlite" to configure PowerDNS to use the SQLite backend.
6383 Compilation can then proceed as usual.
6385 SQLite is included in most PowerDNS binary releases.
6387 ----------------------------------------------------------------------
6389 A.7.2. Setting up the database
6391 Before you can use this backend you first have to set it up and fill it
6392 with data. The default setup conforms to the following schema:
6394 create table domains (
6395 id INTEGER PRIMARY KEY,
6396 name VARCHAR(255) NOT NULL,
6397 master VARCHAR(20) DEFAULT NULL,
6398 last_check INTEGER DEFAULT NULL,
6399 type VARCHAR(6) NOT NULL,
6400 notified_serial INTEGER DEFAULT NULL,
6401 account VARCHAR(40) DEFAULT NULL
6404 CREATE UNIQUE INDEX name_index ON domains(name);
6406 CREATE TABLE records (
6407 id INTEGER PRIMARY KEY,
6408 domain_id INTEGER DEFAULT NULL,
6409 name VARCHAR(255) DEFAULT NULL,
6410 type VARCHAR(6) DEFAULT NULL,
6411 content VARCHAR(255) DEFAULT NULL,
6412 ttl INTEGER DEFAULT NULL,
6413 prio INTEGER DEFAULT NULL,
6414 change_date INTEGER DEFAULT NULL
6417 CREATE INDEX rec_name_index ON records(name);
6418 CREATE INDEX nametype_index ON records(name,type);
6419 CREATE INDEX domain_id ON records(domain_id);
6421 create table supermasters (
6422 ip VARCHAR(25) NOT NULL,
6423 nameserver VARCHAR(255) NOT NULL,
6424 account VARCHAR(40) DEFAULT NULL
6428 This schema contains all elements needed for master, slave and superslave
6431 After you have created the database you probably want to fill it with
6432 data. If you have a BIND zonefile it's as easy as: zone2sql
6433 --zone=myzonefile --gmysql | sqlite powerdns.sqlite, but you can also use
6434 AXFR (or insert data manually if you have too much time ;)).
6436 ----------------------------------------------------------------------
6438 A.7.3. Using the SQLite backend
6440 The last thing you need to do is telling PowerDNS to use the SQLite
6445 gsqlite-database=<path to your SQLite database>
6448 Then you can start PowerDNS and it should notify you that a connection to
6449 the database was made.
6451 ----------------------------------------------------------------------
6455 Table A-8. DB2 backend capabilities
6457 +-------------------+
6459 |-------------+-----|
6461 |-------------+-----|
6463 |-------------+-----|
6465 |-------------+-----|
6466 | Autoserial | Yes |
6467 |-------------+-----|
6468 | Module name | db2 |
6469 |-------------+-----|
6470 | Launch name | db2 |
6471 +-------------------+
6473 PowerDNS is currently ascertaining if this backend can be distributed in
6474 binary form without violating IBM DB2 licensing.
6476 The DB2 backend executes the following queries:
6480 select Content, TimeToLive, Priority, Type, ZoneId, 0 as
6481 ChangeDate, Name from Records where Name = ? and type = ?
6483 Forward By Zone Query
6485 select Content, TimeToLive, Priority, Type, ZoneId, 0 as
6486 ChangeDate, Name from Records where Name = ? and Type = ? and
6491 select Content, TimeToLive, Priority, Type, ZoneId, 0 as
6492 ChangeDate, Name from Records where Name = ?
6496 select Content, TimeToLive, Priority, Type, ZoneId, 0 as
6497 ChangeDate, Name from Records where ZoneId = ?
6499 Configuration settings:
6503 Server name to connect to. Defaults to 'powerdns'. Make sure that
6504 your nameserver is not needed to resolve an IP address needed to
6505 connect as this might lead to a chicken/egg situation.
6509 Username to connect as. Defaults to 'powerdns'.
6513 Password to connect with. Defaults to 'powerdns'.
6515 ----------------------------------------------------------------------
6517 A.9. Bind zone file backend
6519 Table A-9. Bind zone file backend capabilities
6521 +-------------------------------+
6523 |-------------+-----------------|
6525 |-------------+-----------------|
6527 |-------------+-----------------|
6529 |-------------+-----------------|
6531 |-------------+-----------------|
6532 | Module name | none (built in) |
6533 |-------------+-----------------|
6535 +-------------------------------+
6537 Note There is also the Bind2backend which works exactly like this backend
6538 but is far more experimental. In the future it supplant the
6541 The BindBackend started life as a demonstration of the versatility of PDNS
6542 but quickly gained in importance when there appeared to be demand for a
6545 The BindBackend parses a Bind-style named.conf and extracts information
6546 about zones from it. It makes no attempt to honour other configuration
6547 flags, which you should configure (when available) using the PDNS native
6552 Outputs all known parameters related to the bindbackend
6556 Loads the 'example.com' zone which can be queried to determine if
6557 PowerDNS is functioning without configuring database backends.
6561 Location of the Bind configuration file to parse.
6563 bind-check-interval=
6565 How often to check for zone changes. See 'Operation' section.
6569 Enable Huffman compression on zone data. Currently saves around
6570 20% of memory actually used, but slows down operation somewhat.
6572 ----------------------------------------------------------------------
6576 On launch, the BindBackend first parses the named.conf to determine which
6577 zones need to be loaded. These will then be parsed and made available for
6578 serving, as they are parsed. So a named.conf with 100.000 zones may take
6579 20 seconds to load, but after 10 seconds, 50.000 zones will already be
6580 available. While a domain is being loaded, it is not yet available, to
6581 prevent incomplete answers.
6583 Reloading is currently done only when a request for a zone comes in, and
6584 then only after bind-check-interval seconds have passed after the last
6585 check. If a change occurred, access to the zone is disabled, the file is
6586 reloaded, access is restored, and the question is answered. For regular
6587 zones, reloading is fast enough to answer the question which lead to the
6588 reload within the DNS timeout.
6590 If bind-check-interval is specified as zero, no checks will be performed
6591 until the pdns_control reload is given.
6593 ----------------------------------------------------------------------
6595 A.9.2. Pdns_control commands
6597 bind-domain-status domain [domain]
6599 Output status of domain or domains. Can be one of 'seen in
6600 named.conf, not parsed', 'parsed successfully at <time;>' or
6601 'error parsing at line ... at <time>'.
6605 Lists all zones that have problems, and what those problems are.
6607 bind-reload-now domain
6609 Reloads a zone from disk NOW, reporting back results.
6611 ----------------------------------------------------------------------
6615 The BindBackend does not benefit from the packet cache as it is fast
6616 enough on its own. Furthermore, on most systems, there will be no benefit
6617 in using multiple CPUs for the packetcache, so a noticeable speedup can be
6618 attained by specifying distributor-threads=1 in pdns.conf.
6620 ----------------------------------------------------------------------
6622 A.9.4. Master/slave configuration
6626 Works as expected. At startup, no notification storm is performed as this
6627 is generally not useful. Perhaps in the future the Bind Backend will
6628 attempt to store zone metadata in the zone, allowing it to determine if a
6629 zone has changed its serial since the last time notifications were sent
6632 Changes which are discovered when reloading zones do lead to notifications
6635 ----------------------------------------------------------------------
6639 Also works as expected. The Bind backend expects to be able to write to a
6640 directory where a slave domain lives. The incoming zone is stored as
6641 'zonename.RANDOM' and atomically renamed if it is retrieved successfully,
6642 and parsed only then.
6644 In the future, this may be improved so the old zone remains available
6645 should parsing fail.
6647 ----------------------------------------------------------------------
6651 pdns_control offers commands to communicate instructions to PowerDNS.
6652 These are detailed here.
6656 Reread the bind configuration file (named.conf). If parsing fails,
6657 the old configuration remains in force and pdns_control reports
6658 the error. Any newly discovered domains are read, discarded
6659 domains are removed from memory.
6661 Note Except that with 2.9.3, they are not removed from
6666 All zones with a changed timestamp are reloaded at the next
6667 incoming query for them.
6669 ----------------------------------------------------------------------
6673 Table A-10. ODBC backend capabilities
6675 +---------------------------------+
6677 |------------+--------------------|
6678 | Master | Yes (experimental) |
6679 |------------+--------------------|
6680 | Slave | Yes (experimental) |
6681 |------------+--------------------|
6683 |------------+--------------------|
6684 | Autoserial | Yes |
6685 +---------------------------------+
6687 The ODBC backend can retrieve zone information from any source that has a
6688 ODBC driver available.
6690 Note This backend is only available on PowerDNS for Windows.
6692 The ODBC backend needs data in a fixed schema which is the same as the
6693 data needed by the MySQL backend. The create statement will resemble this:
6695 CREATE TABLE records (
6696 id int(11) NOT NULL auto_increment,
6697 domain_id int(11) default NULL,
6698 name varchar(255) default NULL,
6699 type varchar(6) default NULL,
6700 content varchar(255) default NULL,
6701 ttl int(11) default NULL,
6702 prio int(11) default NULL,
6703 change_date int(11) default NULL,
6705 KEY name_index(name),
6706 KEY nametype_index(name,type),
6707 KEY domainid_index(domain_id)
6711 To use the ODBC backend an ODBC source has to be created, to do this see
6712 the section Installing PowerDNS on Microsoft Windows, Chapter 3.
6714 The following configuration settings are available:
6718 Specifies the name of the data source to use.
6722 Specifies the username that has to be used to log into the
6727 Specifies the user's password.
6731 Specifies the name of the table containing the zone information.
6733 The ODBC backend has been tested with Microsoft Access, MySQL (via MyODBC)
6734 and Microsoft SQLServer. As the SQL statements used are very basic, it is
6735 expected to work with many ODBC drivers.
6737 ----------------------------------------------------------------------
6741 Special purpose backend for grandiose performance. Can talk to Tridge's
6742 Trivial Database, or to regular *db tables on disk. Currently only
6743 sparsely documented. Very useful if you need to do >50.000 queries/second,
6744 which we actually measured on the .ORG zone.
6746 More documentation will follow.
6748 ----------------------------------------------------------------------
6752 The main author for this module is Norbert Sendetzky who also has his own
6755 Table A-11. LDAP backend capabilities
6757 +------------------+
6759 |------------+-----|
6761 |------------+-----|
6763 |------------+-----|
6765 |------------+-----|
6766 | Autoserial | Yes |
6767 +------------------+
6769 As of 2.9.6, PowerDNS comes with an LDAP backend. The code for this was
6770 submitted by Norbert Sendetzky.
6772 The following settings are available to configure the LDAP backend:
6776 LDAP host to connect to, defaults to localhost.
6780 LDAP port to connect to, defaults to 389.
6784 Root for DNS searches. Must be configured before the LDAP backend
6789 Distinguished Name to bind with to the LDAP server. Defaults to
6790 the empty string for anonymous bind.
6794 Secret to bind with to LDAP server. Defaults to the empty string
6799 TTL for records with no dnsttl attribute. Defaults to 86400
6802 The schema used is that defined by RFC 1279 and is present in OpenLDAP
6803 under the name 'cosine.schema'. An example LDIF file:
6805 # zone related things including SOA, NS and MX records
6809 objectclass: dnsdomain
6810 objectclass: domainrelatedobject
6812 soarecord: ns.example.dom hostmaster@example.dom 2002010401 1800 3600 604800 84600
6813 nsrecord: ns.example.dom
6814 mxrecord: 10 mail.example.dom
6815 mxrecord: 20 mail2.example.dom
6816 associateddomain: example.dom
6819 # Simple record (mail.example.dom has address 172.168.0.2)
6821 dn: dc=mail,dc=example
6823 objectclass: dnsdomain
6824 objectclass: domainrelatedobject
6826 arecord: 172.168.0.2
6827 associateddomain: mail.example.dom
6829 # There may more than one entry per record
6830 # This is also applicable to all other records including "associateddomain"
6831 # but not for a CNAME record
6833 dn: dc=server,dc=snapcount
6835 objectclass: dnsdomain
6836 objectclass: domainrelatedobject
6839 arecord: 172.168.0.1
6840 associateddomain: server.example.dom
6843 # domain alias ({mail2,ns}.example.dom is CNAME for server.example.dom)
6844 # cnamerecord must only contain one entry
6846 dn: dc=backup,dc=snapcount
6848 objectclass: dnsdomain
6849 objectclass: domainrelatedobject
6851 cnamerecord: server.example.dom
6852 associateddomain: mail2.example.dom
6853 associateddomain: ns.example.dom
6855 ----------------------------------------------------------------------
6857 Appendix B. PDNS internals
6859 PDNS is normally launched by the init.d script but is actually a binary
6860 called pdns_server. This file is started by the start and monitor commands
6861 to the init.d script. Other commands are implemented using the
6864 ----------------------------------------------------------------------
6868 The controlsocket is the means to contact a running PDNS daemon, or as we
6869 now know, a running pdns_server. Over this sockets, instructions can be
6870 sent using the pdns_control program. Like the pdns_server, this program is
6871 normally accessed via the init.d script.
6873 ----------------------------------------------------------------------
6877 To communicate with PDNS over the controlsocket, the pdns_control command
6878 is used. The init.d script also calls pdns_control. The syntax is simple:
6879 pdns_control command arguments. Currently this is most useful for telling
6880 backends to rediscover domains or to force the transmission of
6881 notifications. See Section 13.3.
6883 Besides the commands implemented by the init.d script, for which see
6884 Section 2.3, the following pdns_control commands are available:
6888 Returns counts on the contents of the cache.
6892 Adds a domain to the notification list, causing PDNS to send out
6893 notifications to the nameservers of a domain. Can be used if a
6894 slave missed previous notifications or is generally hard of
6897 notify-host domain host
6899 Same as above but with operator specified IP address as
6900 destination, to be used if you know better than PowerDNS.
6904 Purges the entire Packet Cache - see Chapter 9.
6908 Purges all entries for this exact record name - see Chapter 9.
6912 Purges all cache entries ending on this name, effectively purging
6913 an entire domain - see Chapter 9.
6917 Purges the entire Packet Cache - see Chapter 9.
6921 Purges all entries for this exact record name - see Chapter 9.
6925 Instructs backends that new domains may have appeared in the
6926 database, or, in the case of the Bind backend, in named.conf.
6930 Instructs backends that the contents of domains may have changed.
6931 Many backends ignore this, the Bind backend will check timestamps
6932 for all zones (once queries come in for it) and reload if needed.
6936 Retrieve a slave domain from its master. Done nearly immediatly.
6940 Set a configuration parameter. Currently only the 'query-logging'
6941 parameter can be set.
6945 Reports the uptime of the daemon in human readable form.
6949 returns the version of a running pdns daemon.
6951 ----------------------------------------------------------------------
6955 When launched by the init.d script, pdns_server wraps itself inside a
6956 'guardian'. This guardian monitors the performance of the inner
6957 pdns_server instance which shows up in the process list of your OS as
6958 pdns_server-instance. It is also this guardian that pdns_control talks to.
6959 A STOP is interpreted by the guardian, which causes the guardian to sever
6960 the connection to the inner process and terminate it, after which it
6961 terminates itself. The init.d script DUMP and SHOW commands need to access
6962 the inner process, because the guardian itself does not run a nameserver.
6963 For this purpose, the guardian passes controlsocket requests to the
6964 control console of the inner process. This is the same console as seen
6965 with init.d MONITOR.
6967 ----------------------------------------------------------------------
6969 B.3. Modules & Backends
6971 PDNS has the concept of backends and modules. Non-static PDNS
6972 distributions have the ability to load new modules at runtime, while the
6973 static versions come with a number of modules built in, but cannot load
6976 Related parameters are:
6980 Outputs all known parameters, including those of launched
6981 backends, see below.
6983 --launch=backend,backend1,backend1:name
6985 Launches backends. In its most simple form, supply all backends
6986 that need to be launched. If you find that you need to launch
6987 single backends multiple times, you can specify a name for later
6988 instantiations. In this case, there are 2 instances of backend1,
6989 and the second one is called 'name'. This means that
6990 --backend1-setting is available to configure the first or main
6991 instance, and --backend1-name-setting for the second one.
6993 --load-modules=/directory/libyourbackend.so
6995 If backends are available in nonstandard directories, specify
6996 their location here. Multiple files can be loaded if separated by
6997 commas. Only available in non-static PDNS distributions.
7001 Will list all available modules, both compiled in and in
7002 dynamically loadable modules.
7004 To run on the commandline, use the pdns_server binary. For example, to see
7005 options for the gpgsql backend, use the following:
7007 $ /usr/sbin/pdns_server --launch=gpgsql --help=gpgsql
7010 ----------------------------------------------------------------------
7012 B.4. How PDNS translates DNS queries into backend queries
7014 A DNS query is not a straightforward lookup. Many DNS queries need to
7015 check the backend for additional data, for example to determine of an
7016 unfound record should lead to an NXDOMAIN ('we know about this domain, but
7017 that record does not exist') or an unauthoritative response.
7019 Simplified, without CNAME processing and wildcards, the algorithm is like
7022 When a query for a qname/qtype tuple comes in, it is requested directly
7023 from the backend. If present, PDNS adds the contents of the reply to the
7024 list of records to return. A question tuple may generate multiple answer
7027 Each of these records is now investigated to see if it needs 'additional
7028 processing'. This holds for example for MX records which may point to
7029 hosts for which the PDNS backends also contain data. This involves further
7030 lookups for A or AAAA records.
7032 After all additional processing has been performed, PDNS sieves out all
7033 double records which may well have appeared. The resulting set of records
7034 is added to the answer packet, and sent out.
7036 A zone transfer works by looking up the domain_id of the SOA record of the
7037 name and then listing all records of that domain_id. This is why all
7038 records in a domain need to have the same domain_id.
7040 When a query comes in for an unknown domain, PDNS starts looking for SOA
7041 records of all subdomains of the qname, so no.such.powerdns.com turns into
7042 a SOA query for no.such.powerdns.com, such.powerdns.com, powerdns.com,
7043 com, ''. When a SOA is found, that zone is consulted for relevant NS
7044 instructions which lead to a referral. If nothing is found within the
7045 zone, an authoritative NXDOMAIN is sent out.
7047 If no SOA was found, an unauthoritative no-error is returned.
7049 In reality, each query for a question tuple first involves checking for a
7050 CNAME, unless that resolution has been disabled with the skip-cname
7053 PDNS breaks strict RFC compatability by not always checking for the
7054 presence of a SOA record first. This is unlikely to lead to problems
7057 ----------------------------------------------------------------------
7059 Appendix C. Backend writers' guide
7061 PDNS backends are implemented via a simple yet powerful C++ interface. If
7062 your needs are not met by the PipeBackend, you may want to write your own.
7063 Doing so requires a copy of the PowerDNS Open Source Backend Development
7064 kit which can be found on http://downloads.powerdns.com/releases/dev.
7066 A backend contains zero DNS logic. It need not look for CNAMES, it need
7067 not return NS records unless explicitly asked for, etcetera. All DNS logic
7068 is contained within PDNS itself - backends should simply return records
7069 matching the description asked for.
7071 Warning However, please note that your backend can get queries in aNy
7072 CAsE! If your database is case sensitive, like most are (with the
7073 notable exception of MySQL), you must make sure that you do find
7074 answers which differ only in case.
7076 ----------------------------------------------------------------------
7078 C.1. Simple read-only native backends
7080 Implementing a backend consists of inheriting from the DNSBackend class.
7081 For read-only backends, which do not support slave operation, only the
7082 following methods are relevant:
7088 virtual bool lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt_p=0, int zoneId=-1)=0;
7089 virtual bool list(int domain_id)=0;
7090 virtual bool get(DNSResourceRecord &r)=0;
7091 virtual bool getSOA(const string &name, SOAData &soadata);
7095 Note that the first three methods must be implemented. getSOA() has a
7096 useful default implementation.
7098 The semantics are simple. Each instance of your class only handles one (1)
7099 query at a time. There is no need for locking as PDNS guarantees that your
7100 backend will never be called reentrantly.
7102 Some examples, a more formal specification is down below. A normal lookup
7106 yb.lookup(QType::CNAME,"www.powerdns.com");
7109 Your class should now do everything to start this query. Perform as much
7110 preparation as possible - handling errors at this stage is better for PDNS
7111 than doing so later on. A real error should be reported by throwing an
7114 PDNS will then call the get() method to get DNSResourceRecords back. The
7115 following code illustrates a typical query:
7117 yb.lookup(QType::CNAME,"www.powerdns.com");
7119 DNSResourceRecord rr;
7121 cout<<"Found cname pointing to '"+rr.content+"'"<<endl;
7125 Each zone starts with a Start of Authority (SOA) record. This record is
7126 special so many backends will choose to implement it specially. The
7127 default getSOA() method performs a regular lookup on your backend to
7128 figure out the SOA, so if you have no special treatment for SOA records,
7129 where is no need to implement your own getSOA().
7131 Besides direct queries, PDNS also needs to be able to list a zone, to do
7132 zone transfers for example. Each zone has an id which should be unique
7133 within the backend. To list all records belonging to a zone id, the list()
7134 method is used. Conveniently, the domain_id is also available in the
7137 The following lists the contents of a zone called "powerdns.com".
7140 if(!yb.getSOA("powerdns.com",sd)) // are we authoritative over powerdns.com?
7141 return RCode::NotAuth; // no
7143 yb.list(sd.domain_id);
7145 cout<<rr.qname<<"\t IN "<<rr.qtype.getName()<<"\t"<<rr.content<<endl;
7148 Please note that when so called 'fancy records' (see Chapter 14) are
7149 enabled, a backend can receive wildcard lookups. These have a % as the
7150 first character of the qdomain in lookup.
7152 ----------------------------------------------------------------------
7154 C.1.1. A sample minimal backend
7156 This backend only knows about the host "random.powerdns.com", and
7157 furthermore, only about its A record:
7160 class RandomBackend : public DNSBackend
7164 return false; // we don't support AXFR
7167 void lookup(const QType &type, const string &qdomain, DNSPacket *p, int zoneId)
7169 if(type.getCode()!=QType::A || qdomain!="random.powerdns.com") // we only know about random.powerdns.com A
7170 d_answer=""; // no answer
7173 os<<random()%256<<"."<<random()%256<<"."<<random()%256<<"."<<random()%256;
7174 d_answer=os.str(); // our random ip address
7178 bool get(DNSResourceRecord &rr)
7180 if(!d_answer.empty()) {
7181 rr.qname="random.powerdns.com"; // fill in details
7182 rr.qtype=QType::A; // A record
7183 rr.ttl=86400; // 1 day
7184 rr.content=d_answer;
7186 d_answer=""; // this was the last answer
7190 return false; // no more data
7199 class RandomFactory : public BackendFactory
7202 RandomFactory() : BackendFactory("random") {}
7204 DNSBackend *make(const string &suffix)
7206 return new RandomBackend();
7217 BackendMakers().report(new RandomFactory);
7219 L<<Logger::Info<<" [RandomBackend] This is the randombackend ("__DATE__", "__TIME__") reporting"<<endl;
7223 static RandomLoader randomloader;
7226 This simple backend can be used as an 'overlay'. In other words, it only
7227 knows about a single record, another loaded backend would have to know
7228 about the SOA and NS records and such. But nothing prevents us from
7229 loading it without another backend.
7231 The first part of the code contains the actual logic and should be pretty
7232 straightforward. The second part is a boilerplate 'factory' class which
7233 PDNS calls to create randombackend instances. Note that a 'suffix'
7234 parameter is passed. Real life backends also declare parameters for the
7235 configuration file; these get the 'suffix' appended to them. Note that the
7236 "random" in the constructor denotes the name by which the backend will be
7239 The third part registers the RandomFactory with PDNS. This is a simple C++
7240 trick which makes sure that this function is called on execution of the
7241 binary or when loading the dynamic module.
7243 Please note that a RandomBackend is actually in most PDNS releases. By
7244 default it lives on random.example.com, but you can change that by setting
7247 NOTE: this simple backend neglects to handle case properly! For a more
7248 complete example, see the full pdns-dev distribution as found on the
7251 ----------------------------------------------------------------------
7253 C.1.2. Interface definition
7257 Table C-1. DNSResourceRecord class
7259 +-----------------------------------------------------------------------+
7260 | QType qtype | QType of this record |
7261 |----------------------+------------------------------------------------|
7262 | string qname | name of this record |
7263 |----------------------+------------------------------------------------|
7264 | string content | ASCII representation of right hand side |
7265 |----------------------+------------------------------------------------|
7266 | u_int16_t priority | priority of an MX record. |
7267 |----------------------+------------------------------------------------|
7268 | u_int32_t ttl | Time To Live of this record |
7269 |----------------------+------------------------------------------------|
7270 | int domain_id | ID of the domain this record belongs to |
7271 |----------------------+------------------------------------------------|
7272 | time_t last_modified | If unzero, last time_t this record was changed |
7273 +-----------------------------------------------------------------------+
7275 Table C-2. SOAData struct
7277 +------------------------------------------------------------------------+
7278 | string nameserver | Name of the master nameserver of this zone |
7279 |-----------------------+------------------------------------------------|
7280 | string hostmaster | Hostmaster of this domain. May contain an @ |
7281 |-----------------------+------------------------------------------------|
7282 | u_int32_t serial | Serial number of this zone |
7283 |-----------------------+------------------------------------------------|
7284 | u_int32_t refresh | How often this zone should be refreshed |
7285 |-----------------------+------------------------------------------------|
7286 | u_int32_t retry | How often a failed zone pull should be |
7288 |-----------------------+------------------------------------------------|
7289 | u_int32_t expire | If zone pulls failed for this long, retire |
7291 |-----------------------+------------------------------------------------|
7292 | u_int32_t default_ttl | Difficult |
7293 |-----------------------+------------------------------------------------|
7294 | int domain_id | The ID of the domain within this backend. Must |
7296 |-----------------------+------------------------------------------------|
7297 | | Pointer to the backend that feels |
7298 | DNSBackend *db | authoritative for a domain and can act as a |
7300 +------------------------------------------------------------------------+
7304 void lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt=0,
7307 This function is used to initiate a straight lookup for a record
7308 of name 'qdomain' and type 'qtype'. A QType can be converted into
7309 an integer by invoking its getCode() method and into a string with
7312 The original question may or may not be passed in the pointer p.
7313 If it is, you can retrieve (from 1.99.11 onwards) information
7314 about who asked the question with the getRemote(DNSPacket *)
7315 method. Alternatively, bool getRemote(struct sockaddr *sa,
7316 socklen_t *len) is available.
7318 Note that qdomain can be of any case and that your backend should
7319 make sure it is in effect case insensitive. Furthermore, the case
7320 of the original question should be retained in answers returned by
7323 Finally, the domain_id might also be passed indicating that only
7324 answers from the indicated zone need apply. This can both be used
7325 as a restriction or as a possible speedup, hinting your backend
7326 where the answer might be found.
7328 If initiated succesfully, as indicated by returning true, answers
7329 should be made available over the get() method.
7331 Should throw an AhuException if an error occured accessing the
7332 database. Returning otherwise indicates that the query was started
7333 succesfully. If it is known that no data is available, no
7334 exception should be thrown! An exception indicates that the
7335 backend considers itself broken - not that no answers are
7336 available for a question.
7338 It is legal to return here, and have the first call to get()
7339 return false. This is interpreted as 'no data'
7341 bool list(int domain_id)
7343 Initiates a list of the indicated domain. Records should then be
7344 made available via the get() method. Need not include the SOA
7345 record. If it is, PDNS will not get confused.
7347 Should return false if the backend does not consider itself
7348 authoritative for this zone. Should throw an AhuException if an
7349 error occured accessing the database. Returning true indicates
7350 that data is or should be available.
7352 bool get(DNSResourceRecord &rr)
7354 Request a DNSResourceRecord from a query started by get() of
7355 list(). If this functions returns true, rr has been filled with
7356 data. When it returns false, no more data is available, and rr
7357 does not contain new data. A backend should make sure that it
7358 either fills out all fields of the DNSResourceRecord or resets
7359 them to their default values.
7361 The qname field of the DNSResourceRecord should be filled out with
7362 the exact qdomain passed to lookup, preserving its case. So if a
7363 query for 'CaSe.yourdomain.com' comes in and your database
7364 contains dat afor 'case.yourdomain.com', the qname field of rr
7365 should contin 'CaSe.yourdomain.com'!
7367 Should throw an AhuException in case a database error occurred.
7369 bool getSOA(const string &name, SOAData &soadata)
7371 If the backend considers itself authoritative over domain name,
7372 this method should fill out the passed SOAData structure and
7373 return a positive number. If the backend is functioning correctly,
7374 but does not consider itself authoritative, it should return 0. In
7375 case of errors, an AhuException should be thrown.
7377 ----------------------------------------------------------------------
7379 C.2. Reporting errors
7381 To report errors, the Logger class is available which works mostly like an
7382 iostream. Example usage is as shown above in the RandomBackend. Note that
7383 it is very important that each line is ended with endl as your message
7384 won't be visible otherwise.
7386 To indicate the importance of an error, the standard syslog errorlevels
7387 are available. They can be set by outputting Logger::Critical,
7388 Logger::Error, Logger::Warning, Logger::Notice, Logger::Info or
7389 Logger::Debug to L, in descending order of graveness.
7391 ----------------------------------------------------------------------
7393 C.3. Declaring and reading configuration details
7395 It is highly likely that a backend needs configuration details. On launch,
7396 these parameters need to be declared with PDNS so it knows it should
7397 accept them in the configuration file and on the commandline. Furthermore,
7398 they will be listed in the output of --help.
7400 Declaring arguments is done by implementing the member function
7401 declareArguments() in the factory class of your backend. PDNS will call
7402 this method after launching the backend.
7404 In the declareArguments() method, the function declare() is available. The
7407 void declareArguments(const string &suffix="")
7409 This method is called to allow a backend to register configurable
7410 parameters. The suffix is the sub-name of this module. There is no
7411 need to touch this suffix, just pass it on to the declare method.
7413 void declare(const string &suffix, const string ¶m, const string
7414 &explanation, const string &value)
7416 The suffix is passed to your method, and can be passed on to
7417 declare. param is the name of your parameter. explanation is what
7418 will appear in the output of --help. Furthermore, a default value
7419 can be supplied in the value parameter.
7421 A sample implementation:
7423 void declareArguments(const string &suffix)
7425 declare(suffix,"dbname","Pdns backend database name to connect to","powerdns");
7426 declare(suffix,"user","Pdns backend user to connect as","powerdns");
7427 declare(suffix,"host","Pdns backend host to connect to","");
7428 declare(suffix,"password","Pdns backend password to connect with","");
7432 After the arguments have been declared, they can be accessed from your
7433 backend using the mustDo(), getArg() and getArgAsNum() methods. The are
7434 defined as follows in the DNSBackend class:
7436 void setArgPrefix(const string &prefix)
7438 Must be called before any of the other accessing functions are
7439 used. Typical usage is 'setArgPrefix("mybackend"+suffix)' in the
7440 constructor of a backend.
7442 bool mustDo(const string &key)
7444 Returns true if the variable key is set to anything but 'no'.
7446 const string& getArg(const string &key)
7448 Returns the exact value of a parameter.
7450 int getArgAsNum(const string &key)
7452 Returns the numerical value of a parameter. Uses atoi() internally
7454 Sample usage from the BindBackend, using the bind-example-zones and
7455 bind-config parameters.
7457 if(mustDo("example-zones")) {
7458 insert(0,"www.example.com","A","1.2.3.4");
7463 if(!getArg("config").empty()) {
7466 BP.parse(getArg("config"));
7471 ----------------------------------------------------------------------
7473 C.4. Read/write slave-capable backends
7475 The backends above are 'natively capable' in that they contain all data
7476 relevant for a domain and do not pull in data from other nameservers. To
7477 enable storage of information, a backend must be able to do more.
7479 Before diving into the details of the implementation some theory is in
7480 order. Slave domains are pulled from the master. PDNS needs to know for
7481 which domains it is to be a slave, and for each slave domain, what the IP
7482 address of the master is.
7484 A slave zone is pulled from a master, after which it is 'fresh', but this
7485 is only temporary. In the SOA record of a zone there is a field which
7486 specifies the 'refresh' interval. After that interval has elapsed, the
7487 slave nameserver needs to check at the master ff the serial number there
7488 is higher than what is stored in the backend locally.
7490 If this is the case, PDNS dubs the domain 'stale', and schedules a
7491 transfer of data from the remote. This transfer remains scheduled until
7492 the serial numbers remote and locally are identical again.
7494 This theory is implemented by the getUnfreshSlaveInfos method, which is
7495 called on all backends periodically. This method fills a vector of
7496 SlaveDomains with domains that are unfresh and possibly stale.
7498 PDNS then retrieves the SOA of those domains remotely and locally and
7499 creates a list of stale domains. For each of these domains, PDNS starts a
7500 zonetransfer to resynchronise. Because zone transfers can fail, it is
7501 important that the interface to the backend allows for transaction
7502 semantics because a zone might otherwise be left in a halfway updated
7505 The following excerpt from the DNSBackend shows the relevant functions:
7510 virtual bool getDomainInfo(const string &domain, DomainInfo &di);
7511 virtual bool isMaster(const string &name, const string &ip);
7512 virtual bool startTransaction(const string &qname, int id);
7513 virtual bool commitTransaction();
7514 virtual bool abortTransaction();
7515 virtual bool feedRecord(const DNSResourceRecord &rr);
7516 virtual void getUnfreshSlaveInfos(vector<DomainInfo>* domains);
7517 virtual void setFresh(int id);
7522 The mentioned DomainInfo struct looks like this:
7524 Table C-3. DomainInfo struct
7526 +------------------------------------------------------------------------+
7527 | int id | ID of this zone within this backend |
7528 |---------------------------------+--------------------------------------|
7529 | string master | IP address of the master of this |
7530 | | domain, if any |
7531 |---------------------------------+--------------------------------------|
7532 | u_int32_t serial | Serial number of this zone |
7533 |---------------------------------+--------------------------------------|
7534 | u_int32_t notified_serial | Last serial number of this zone that |
7535 | | slaves have seen |
7536 |---------------------------------+--------------------------------------|
7537 | time_t last_check | Last time this zone was checked over |
7538 | | at the master for changes |
7539 |---------------------------------+--------------------------------------|
7540 | enum {Master,Slave,Native} kind | Type of zone |
7541 |---------------------------------+--------------------------------------|
7542 | | Pointer to the backend that feels |
7543 | DNSBackend *backend | authoritative for a domain and can |
7544 | | act as a slave |
7545 +------------------------------------------------------------------------+
7547 These functions all have a default implementation that returns false -
7548 which explains that these methods can be omitted in simple backends.
7549 Furthermore, unlike with simple backends, a slave capable backend must
7550 make sure that the 'DNSBackend *db' field of the SOAData record is filled
7551 out correctly - it is used to determine which backend will house this
7554 bool isMaster(const string &name, const string &ip);
7556 If a backend considers itself a slave for the domain name and if
7557 the IP address in ip is indeed a master, it should return true.
7558 False otherwise. This is a first line of checks to guard against
7559 reloading a domain unnecessarily.
7561 void getUnfreshSlaveInfos(vector<DomainInfo>* domains)
7563 When called, the backend should examine its list of slave domains
7564 and add any unfresh ones to the domains vector.
7566 bool getDomainInfo(const string &name, DomainInfo & di)
7568 This is like getUnfreshSlaveInfos, but for a specific domain. If
7569 the backend considers itself authoritative for the named zone, di
7570 should be filled out, and 'true' be returned. Otherwise return
7573 bool startTransaction(const string &qname, int id)
7575 When called, the backend should start a transaction that can be
7576 committed or rolled back atomically later on. In SQL terms, this
7577 function should BEGIN a transaction and DELETE all records.
7579 bool feedRecord(const DNSResourceRecord &rr)
7583 bool commitTransaction();
7585 Make the changes effective. In SQL terms, execute COMMIT.
7587 bool abortTransaction();
7589 Abort changes. In SQL terms, execute ABORT.
7593 Indicate that a domain has either been updated or refreshed
7594 without the need for a retransfer. This causes the domain to
7595 vanish from the vector modified by getUnfreshSlaveInfos().
7597 PDNS will always call startTransaction() before making calls to
7598 feedRecord(). Although it is likely that abortTransaction() will be called
7599 in case of problems, backends should also be prepared to abort from their
7602 The actual code in PDNS is currently (1.99.9):
7605 resolver.axfr(remote,domain.c_str());
7607 db->startTransaction(domain, domain_id);
7609 L<<Logger::Error<<"AXFR started for '"<<domain<<"'"<<endl;
7610 Resolver::res_t recs;
7612 while(resolver.axfrChunk(recs)) {
7613 for(Resolver::res_t::const_iterator i=recs.begin();i!=recs.end();++i) {
7617 db->commitTransaction();
7618 db->setFresh(domain_id);
7619 L<<Logger::Error<<"AXFR done for '"<<domain<<"'"<<endl;
7622 ----------------------------------------------------------------------
7624 C.4.1. Supermaster/Superslave capability
7626 A backend that wants to act as a 'superslave' for a master should
7627 implement the following method:
7631 virtual bool superMasterBackend(const string &ip, const string &domain, const vector<DNSResourceRecord>&nsset, string *account, DNSBackend **db)
7635 This function gets called with the IP address of the potential
7636 supermaster, the domain it is sending a notification for and the set of NS
7637 records for this domain at that IP address.
7639 Using the supplied data, the backend needs to determine if this is a
7640 bonafide 'supernotification' which should be honoured. If it decides that
7641 it should, the supplied pointer to 'account' needs to be filled with the
7642 configured name of the supermaster (if accounting is desired), and the db
7643 needs to be filled with a pointer to your backend.
7645 Supermaster/superslave is a complicated concept, if this is all unclear
7648 ----------------------------------------------------------------------
7650 C.5. Read/write master-capable backends
7652 In order to be a useful master for a domain, notifies must be sent out
7653 whenever a domain is changed. Periodically, PDNS queries backends for
7654 domains that may have changed, and sends out notifications for slave
7657 In order to do so, PDNS calls the getUpdatedMasters() method. Like the
7658 getUnfreshSlaveInfos() function mentioned above, this should add changed
7659 domain names to the vector passed.
7661 The following excerpt from the DNSBackend shows the relevant functions:
7666 virtual void getUpdatedMasters(vector<DomainInfo>* domains);
7667 virtual void setNotifed(int id, u_int32_t serial);
7672 These functions all have a default implementation that returns false -
7673 which explains that these methods can be omitted in simple backends.
7674 Furthermore, unlike with simple backends, a slave capable backend must
7675 make sure that the 'DNSBackend *db' field of the SOAData record is filled
7676 out correctly - it is used to determine which backend will house this
7679 void getUpdatedMasters(vector<DomainInfo>* domains)
7681 When called, the backend should examine its list of master domains
7682 and add any changed ones to the DomainInfo vector
7684 bool setNotified(int domain_id, u_int32_t serial)
7686 Indicate that notifications have been queued for this domain and
7687 that it need not be considered 'updated' anymore
7689 ----------------------------------------------------------------------
7691 Appendix D. Compiling PowerDNS
7693 D.1. Compiling PowerDNS on Unix
7695 Note For now, see the Open Source PowerDNS site. ./configure ; make ; make
7696 install will do The Right Thing for most people.
7698 PowerDNS can becompiled with modules built in, or with modules designed to
7699 be loaded at runtime. All that is configured before compiling using the
7700 well known autoconf/automake system.
7702 To compile in modules, specify them as --with-modules="mod1 mod2 mod3",
7703 substituting the desired module names. Each backend has a module name in
7704 the table at the beginning of its section.
7706 To compile a module for inclusion at runtime, which is great if you are a
7707 unix vendor, use --with-dynmodules="mod1 mod2 mod3". These modules then
7708 end up as .so files in the compiled libdir.
7710 ----------------------------------------------------------------------
7714 Known to compile with gcc, but only since 2.9.8. AIX lacks POSIX
7715 semaphores so they need to be emulated, as with MacOS X.
7717 ----------------------------------------------------------------------
7721 Works fine, but use gmake. Pipe backend is currently broken, for reasons,
7722 see Section A.1. Due to the threading model of FreeBSD, PowerDNS does not
7723 benefit from additional CPUs on the system.
7725 ----------------------------------------------------------------------
7729 Linux is probably the best supported platform as most of the main coders
7730 are Linux users. The static DEB distribution is known to have problems on
7731 Debian 'Sid', but that doesn't matter as PowerDNS is a native part of
7732 Debian 'Sid'. Just apt-get!
7734 ----------------------------------------------------------------------
7738 Did compile at one point but maintenance has lapsed. Let us know if you
7739 can provide us with a login on MacOS X or if you want to help.
7741 ----------------------------------------------------------------------
7745 Compiles but then does not work very well. We hear that it may work with
7746 more recent versions of gcc, please let us know on
7747 <pdns-dev@mailman.powerdns.com>.
7749 ----------------------------------------------------------------------
7753 Solaris 7 is supported, but only just. AAAA records do not work on Solaris
7754 7. Solaris 8 and 9 work fine. The 'Sunpro' compiler has not been tried but
7755 is reported to be lacking large parts of the Standard Template Library,
7756 which PowerDNS relies on heavily. Use gcc and gmake (if available).
7757 Regular Solaris make has some issues with some PowerDNS Makefile
7760 When compiling, make sure that you have /usr/ccs/bin in your path.
7761 Furthermore, with some versions of MySQL, you may have to add
7762 "LDFLAGS=-lz" before ./configure.
7764 ----------------------------------------------------------------------
7766 D.2. Compiling PowerDNS on Windows
7768 By Michel Stol (<michel@powerdns.com>).
7770 ----------------------------------------------------------------------
7774 I will assume these things from you:
7776 You have the PowerDNS sources.
7778 There's not much to compile without the source files, eh? :)
7780 You are using Microsoft Visual C++. If you get it to compile using a free
7781 compiler, please let us know!
7783 From the day that we began porting the UNIX PowerDNS sources to
7784 Microsoft Windows we used Microsoft Visual C++ as our development
7785 environment of choice.
7787 We used Visual C++ 6.0 to compile all sources (both standard
7788 version and SP5). Other versions (including Visual C++ .NET) are
7791 You are using Microsoft Windows NT, 2000 or XP
7793 I will assume that the system where you want to compile the
7794 sources on is running Microsoft Windows NT, 2000 or XP. These are
7795 the operating systems that where found running PowerDNS for
7798 Note You probably can compile the sources on other Windows
7799 versions too, but that is currently untested.
7801 You are using an English Windows version.
7803 Troughout this document I will use the English names for menu
7804 items, names etc., so if you are running a non-English Windows or
7805 MSVC version you have to translate those things yourself. But I
7806 don't think that would be a big problem.
7808 ----------------------------------------------------------------------
7812 Although we tried to keep PowerDNS for Windows' dependencies down to a
7813 minimum, you will still need some programs and libraries to be able to
7814 compile the sources.
7816 ----------------------------------------------------------------------
7818 D.2.2.1. pthreads for Windows
7820 The pthreads for Windows library is a Windows implementation of the POSIX
7821 threads specification, which is used a lot in UNIX programs.
7823 PowerDNS uses pthreads too, and to ease the porting process we decided not
7824 to reinvent the wheel, but to use pthreads for Windows instead.
7826 ----------------------------------------------------------------------
7828 D.2.2.1.1. Getting pthreads for Windows
7830 Pthreads for Windows is available from anonymous ftp at
7831 ftp://sources.redhat.com/pub/pthreads-win32/. You should download the
7832 latest pthreads-YYYY-MM-DD.exe file.
7834 Note PowerDNS for Windows was tested with the snapshot of 2002-03-02 of
7837 For more information you can visit the pthreads for Windows homepage at
7838 http://sources.redhat.com/pthreads-win32/
7840 ----------------------------------------------------------------------
7842 D.2.2.2. Installing pthreads for Windows
7844 To install the pthreads for Windows library you have to locate your
7845 pthreads-YYYY-MM-DD.exe file and start it.
7847 After starting the executable a self-extractor dialog will show up where
7848 you can specify where to extract the contents of the file. When you
7849 selected a location you can press the Extract button to extract all
7850 content to the target directory.
7852 The library is now installed, we still have to tell Visual C++ where it's
7853 located though, more on that later.
7855 ----------------------------------------------------------------------
7857 D.2.3. Nullsoft Installer
7859 For our installation program we used Nullsoft's Installer System (NSIS).
7860 We used NSIS because it's easy to use, versatile and free (and it uses
7861 SuperPiMP(TM) technology, but they refuse to tell us what it is ;)). If
7862 the name Nullsoft rings a bell, it's because they're the guys who made
7865 ----------------------------------------------------------------------
7867 D.2.3.1. Getting the Nullsoft Installer
7869 The Nullsoft Installer can be downloaded at their website, which is
7870 located at http://www.nullsoft.com/free/nsis/. The file that you should
7871 download is called nsisXXX.exe (where XXX is the latest version).
7873 Note You can find the NSIS documentation at that website too.
7875 ----------------------------------------------------------------------
7877 D.2.3.2. Installing the Nullsoft Installer
7879 Installing NSIS is easy. All there is to it is locating the installer and
7880 execute it. Then just follow the installation steps.
7882 ----------------------------------------------------------------------
7884 D.2.4. Setting up the build-environment
7886 Before starting Microsoft Visual C++ and compile PowerDNS for Windows, you
7887 first have to set up your build environment.
7889 ----------------------------------------------------------------------
7891 D.2.4.1. Make Microsoft Visual C++ recognize *.cc and *.hh (optional)
7893 All PowerDNS source files are in the form name.cc, and all header files in
7894 the form name.hh. These extensions aren't recognized by MSVC by default,
7895 so you might want to change that first.
7897 Note Only perform this step if you want to be able to edit the *.cc and
7900 Caution If you decide to perform this step, remember that it requires
7901 modification of the Windows registry, always make a backup before
7904 Ok, after that word of caution we can now proceed. You have to follow
7907 1. Start the registry editor by entering regedit.exe in the run prompt
7910 2. Right click on HKEY_CLASSES_ROOT and select New->Key. A new key will
7911 appear, change that key to ".cc", then change the default value to
7914 Then perform the same step for ".hh" (use "hfile" instead of
7917 3. Go to HKEY_CURRENT_USER\Software\Microsoft\DevStudio\6.0\Build
7918 System\Components\Platforms\Win32 (x86)\Tools\32-bit C/C++ Compiler
7919 for 80x86. And add ";*.cc" to the Input_Spec value (so that it becomes
7920 "*.c;*.cpp;*.cxx;*.cc").
7922 Note If you happen to use another platform (like alpha) to
7923 compile the sources, you have to do the step above for
7926 4. Go to HKEY_CURRENT_USER\Software\Microsoft\DevStudio\6.0\Search. And
7927 add ";*.cc;*.hh" to the FIF_Filter value (so that it becomes
7928 "*.c;*.cpp;*.cxx;*.tli;*.h;*.tlh;*.inl;*.rc;*.cc;*.hh").
7930 5. Finally change HKEY_CURRENT_USER\Software\Microsoft\DevStudio\6.0\Text
7931 Editor\Tabs/Language Settings\C/C++. And add ";cc;hh" to the
7932 FileExtensions value (so that it becomes
7933 "cpp;cxx;c;h;hxx;hpp;inl;tlh;tli;rc;rc2;hh;cc").
7935 6. Close the registry editor.
7937 Now should MSVC properly recognize the files as being C++.
7939 ----------------------------------------------------------------------
7941 D.2.4.2. Setting Microsoft Visual C++'s directories
7943 MSVC needs to locate some include files, libraries and executables when it
7944 has to build PowerDNS for Windows. We are now going to tell MSVC where to
7947 To enter the directory dialog you have to go to
7948 Tools->Options...->Directories.
7950 ----------------------------------------------------------------------
7952 D.2.4.2.1. Setting the pthreads directories
7954 When you are in the directory dialog you can add the pthreads for Windows
7957 First add the include directory, to do this you have to select Include
7958 files from the Show directories for: combobox. Then press the New button
7959 and browse to the include directory of pthreads (ie. C:\pthreads\include).
7961 Then switch to Library files and add the library directory (ie.
7962 C:\pthreads\lib) using the same method as above.
7964 ----------------------------------------------------------------------
7966 D.2.4.2.2. Setting the Nullsoft Installer directory
7968 While still being in the directory dialog, switch to Executable files and
7969 add the Nullsoft Installer directory (ie. C:\Program Files\NSIS) to the
7972 ----------------------------------------------------------------------
7976 Finally, after all the reading, installing and configuring we are ready to
7977 start compiling PowerDNS for Windows.
7979 ----------------------------------------------------------------------
7981 D.2.5.1. Starting the compilation
7983 To start the compilation you first have to open the PowerDNS workspace
7984 (powerdns.dsw) using explorer or from the File->Open Workspace... menu in
7987 After you opened the workspace you can start compiling. Check all the
7988 checkboxes in the Build->Batch Build... menu and press the Build button.
7990 Now cross your fingers and go make some coffee or tea while compiling
7991 PowerDNS for Windows. :)
7993 ----------------------------------------------------------------------
7995 D.2.5.2. Yay! It compiled
7997 Congratulations, you have now compiled PowerDNS for Windows!
7999 All the release builds of the binaries are in the Release directory
8000 (including the generated installer). The debug builds are in the, guess
8001 what, Debug directory.
8003 Now you can start installing PowerDNS, but that's beyond the scope of this
8004 document. See the online documentation for more information about that.
8006 ----------------------------------------------------------------------
8008 D.2.5.3. What if it went wrong?
8010 If the compilation fails, then try reading this article again, and again
8011 to see if you did something wrong.
8013 If you are pretty sure that it's a bug, either in the PowerDNS sources,
8014 the build system or in this article, then please send an e-mail to
8015 <pdns-dev@mailman.powerdns.com> describing your problem. We will then try
8018 ----------------------------------------------------------------------
8020 D.2.6. Miscellaneous
8022 Some miscellaneous information.
8024 ----------------------------------------------------------------------
8028 Michel Stol would like to thank these people:
8032 For writing the wonderfull PowerDNS software and learning me stuff
8033 that I'd otherwise never had learned.
8037 For being great colleagues.
8039 The pthreads-win32 crew (see the pthreads-win32 CONTRIBUTORS file).
8041 For easing our porting process by writing a great Windows
8042 implementation of pthreads.
8044 The guys over at Nullsoft.
8046 For creating the Nullsoft Installer System (NSIS), and Winamp, the
8047 program we use every day to make a lot of noise in the office.
8049 ----------------------------------------------------------------------
8051 D.2.6.2. Contact information
8053 If you have a comment, or a bug report concerning either this document or
8054 the PowerDNS sources you can contact <pdns-dev@mailman.powerdns.com>
8056 For general information about PowerDNS, the pdns server, express,
8057 documentation etc. I advice you to visit http://www.powerdns.com/
8059 If you are interested in buying PowerDNS you can send a mail to
8060 <sales@powerdns.com> or you can visit the PowerDNS website at
8061 http://www.powerdns.com/pdns/
8063 If you want to praise my work, ask me to marry you, deposit $1.000.000 on
8064 my bank account or flame me to death, then you can mail me at
8065 <michel@powerdns.com> :)
8067 ----------------------------------------------------------------------
8069 D.2.6.3. Legal information
8071 Microsoft, Visual C++, Windows, Windows NT, Windows 2000, Windows XP and
8072 Win32 are either registered trademarks or trademarks of Microsoft
8073 Corporation in the U.S.A. and/or other countries.
8075 Other product and company names mentioned herein may be the trademarks of
8076 their respective owners.
8078 ----------------------------------------------------------------------
8080 Appendix E. PowerDNS license (GNU General Public License version 2)
8082 GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION
8085 \r 0. This License applies to any program or other work which contains a
8086 notice placed by the copyright holder saying it may be distributed under
8087 the terms of this General Public License. The "Program", below, refers to
8088 any such program or work, and a "work based on the Program" means either
8089 the Program or any derivative work under copyright law: that is to say, a
8090 work containing the Program or a portion of it, either verbatim or with
8091 modifications and/or translated into another language. (Hereinafter,
8092 translation is included without limitation in the term "modification".)
8093 Each licensee is addressed as "you".
8095 Activities other than copying, distribution and modification are not
8096 covered by this License; they are outside its scope. The act of running
8097 the Program is not restricted, and the output from the Program is covered
8098 only if its contents constitute a work based on the Program (independent
8099 of having been made by running the Program). Whether that is true depends
8100 on what the Program does.
8102 1. You may copy and distribute verbatim copies of the Program's source
8103 code as you receive it, in any medium, provided that you conspicuously and
8104 appropriately publish on each copy an appropriate copyright notice and
8105 disclaimer of warranty; keep intact all the notices that refer to this
8106 License and to the absence of any warranty; and give any other recipients
8107 of the Program a copy of this License along with the Program.
8109 You may charge a fee for the physical act of transferring a copy, and you
8110 may at your option offer warranty protection in exchange for a fee.
8112 2. You may modify your copy or copies of the Program or any portion of it,
8113 thus forming a work based on the Program, and copy and distribute such
8114 modifications or work under the terms of Section 1 above, provided that
8115 you also meet all of these conditions:
8117 a) You must cause the modified files to carry prominent notices stating
8118 that you changed the files and the date of any change.
8120 b) You must cause any work that you distribute or publish, that in whole
8121 or in part contains or is derived from the Program or any part thereof, to
8122 be licensed as a whole at no charge to all third parties under the terms
8125 c) If the modified program normally reads commands interactively when run,
8126 you must cause it, when started running for such interactive use in the
8127 most ordinary way, to print or display an announcement including an
8128 appropriate copyright notice and a notice that there is no warranty (or
8129 else, saying that you provide a warranty) and that users may redistribute
8130 the program under these conditions, and telling the user how to view a
8131 copy of this License. (Exception: if the Program itself is interactive but
8132 does not normally print such an announcement, your work based on the
8133 Program is not required to print an announcement.) These requirements
8134 apply to the modified work as a whole. If identifiable sections of that
8135 work are not derived from the Program, and can be reasonably considered
8136 independent and separate works in themselves, then this License, and its
8137 terms, do not apply to those sections when you distribute them as separate
8138 works. But when you distribute the same sections as part of a whole which
8139 is a work based on the Program, the distribution of the whole must be on
8140 the terms of this License, whose permissions for other licensees extend to
8141 the entire whole, and thus to each and every part regardless of who wrote
8144 Thus, it is not the intent of this section to claim rights or contest your
8145 rights to work written entirely by you; rather, the intent is to exercise
8146 the right to control the distribution of derivative or collective works
8147 based on the Program.
8149 In addition, mere aggregation of another work not based on the Program
8150 with the Program (or with a work based on the Program) on a volume of a
8151 storage or distribution medium does not bring the other work under the
8152 scope of this License.
8154 3. You may copy and distribute the Program (or a work based on it, under
8155 Section 2) in object code or executable form under the terms of Sections 1
8156 and 2 above provided that you also do one of the following:
8158 a) Accompany it with the complete corresponding machine-readable source
8159 code, which must be distributed under the terms of Sections 1 and 2 above
8160 on a medium customarily used for software interchange; or,
8162 b) Accompany it with a written offer, valid for at least three years, to
8163 give any third party, for a charge no more than your cost of physically
8164 performing source distribution, a complete machine-readable copy of the
8165 corresponding source code, to be distributed under the terms of Sections 1
8166 and 2 above on a medium customarily used for software interchange; or,
8168 \r c) Accompany it with the information you received as to the offer to
8169 distribute corresponding source code. (This alternative is allowed only
8170 for noncommercial distribution and only if you received the program in
8171 object code or executable form with such an offer, in accord with
8172 Subsection b above.)
8174 The source code for a work means the preferred form of the work for making
8175 modifications to it. For an executable work, complete source code means
8176 all the source code for all modules it contains, plus any associated
8177 interface definition files, plus the scripts used to control compilation
8178 and installation of the executable. However, as a special exception, the
8179 source code distributed need not include anything that is normally
8180 distributed (in either source or binary form) with the major components
8181 (compiler, kernel, and so on) of the operating system on which the
8182 executable runs, unless that component itself accompanies the executable.
8184 If distribution of executable or object code is made by offering access to
8185 copy from a designated place, then offering equivalent access to copy the
8186 source code from the same place counts as distribution of the source code,
8187 even though third parties are not compelled to copy the source along with
8188 the object code. 4. You may not copy, modify, sublicense, or distribute
8189 the Program except as expressly provided under this License. Any attempt
8190 otherwise to copy, modify, sublicense or distribute the Program is void,
8191 and will automatically terminate your rights under this License. However,
8192 parties who have received copies, or rights, from you under this License
8193 will not have their licenses terminated so long as such parties remain in
8196 5. You are not required to accept this License, since you have not signed
8197 it. However, nothing else grants you permission to modify or distribute
8198 the Program or its derivative works. These actions are prohibited by law
8199 if you do not accept this License. Therefore, by modifying or distributing
8200 the Program (or any work based on the Program), you indicate your
8201 acceptance of this License to do so, and all its terms and conditions for
8202 copying, distributing or modifying the Program or works based on it.
8204 6. Each time you redistribute the Program (or any work based on the
8205 Program), the recipient automatically receives a license from the original
8206 licensor to copy, distribute or modify the Program subject to these terms
8207 and conditions. You may not impose any further restrictions on the
8208 recipients' exercise of the rights granted herein. You are not responsible
8209 for enforcing compliance by third parties to this License.
8211 7. If, as a consequence of a court judgment or allegation of patent
8212 infringement or for any other reason (not limited to patent issues),
8213 conditions are imposed on you (whether by court order, agreement or
8214 otherwise) that contradict the conditions of this License, they do not
8215 excuse you from the conditions of this License. If you cannot distribute
8216 so as to satisfy simultaneously your obligations under this License and
8217 any other pertinent obligations, then as a consequence you may not
8218 distribute the Program at all. For example, if a patent license would not
8219 permit royalty-free redistribution of the Program by all those who receive
8220 copies directly or indirectly through you, then the only way you could
8221 satisfy both it and this License would be to refrain entirely from
8222 distribution of the Program.
8224 If any portion of this section is held invalid or unenforceable under any
8225 particular circumstance, the balance of the section is intended to apply
8226 and the section as a whole is intended to apply in other circumstances.
\r
8228 It is not the purpose of this section to induce you to infringe any
8229 patents or other property right claims or to contest validity of any such
8230 claims; this section has the sole purpose of protecting the integrity of
8231 the free software distribution system, which is implemented by public
8232 license practices. Many people have made generous contributions to the
8233 wide range of software distributed through that system in reliance on
8234 consistent application of that system; it is up to the author/donor to
8235 decide if he or she is willing to distribute software through any other
8236 system and a licensee cannot impose that choice.
8238 This section is intended to make thoroughly clear what is believed to be a
8239 consequence of the rest of this License. 8. If the distribution and/or use
8240 of the Program is restricted in certain countries either by patents or by
8241 copyrighted interfaces, the original copyright holder who places the
8242 Program under this License may add an explicit geographical distribution
8243 limitation excluding those countries, so that distribution is permitted
8244 only in or among countries not thus excluded. In such case, this License
8245 incorporates the limitation as if written in the body of this License.
8247 9. The Free Software Foundation may publish revised and/or new versions of
8248 the General Public License from time to time. Such new versions will be
8249 similar in spirit to the present version, but may differ in detail to
8250 address new problems or concerns.
8252 Each version is given a distinguishing version number. If the Program
8253 specifies a version number of this License which applies to it and "any
8254 later version", you have the option of following the terms and conditions
8255 either of that version or of any later version published by the Free
8256 Software Foundation. If the Program does not specify a version number of
8257 this License, you may choose any version ever published by the Free
8258 Software Foundation.
8260 10. If you wish to incorporate parts of the Program into other free
8261 programs whose distribution conditions are different, write to the author
8262 to ask for permission. For software which is copyrighted by the Free
8263 Software Foundation, write to the Free Software Foundation; we sometimes
8264 make exceptions for this. Our decision will be guided by the two goals of
8265 preserving the free status of all derivatives of our free software and of
8266 promoting the sharing and reuse of software generally.
8270 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
8271 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
8272 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
8273 PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
8274 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
8275 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
8276 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
8277 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
8278 REPAIR OR CORRECTION.
\r
8280 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
8281 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
8282 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
8283 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
8284 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
8285 LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
8286 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
8287 WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
8288 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
8290 END OF TERMS AND CONDITIONS
projects / packages / pdns.git / blob