Context Navigation

pdns.sgml @ 15

Visit:

Revision 15, 243.2 KB (checked in by ahu, 10 years ago)
juh
Property svn:eol-style set to `native` Property svn:keywords set to `author date id revision`

Line
1	<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2
3	<Book>
4
5	<BookInfo>
6
7	<Title>PowerDNS manual</Title>
8	<AUTHOR>
9	<affiliation>
10	<orgname>PowerDNS BV</orgname>
11	<address>
12	<email>pdns@powerdns.com</email>
13	</address>
14
15	</affiliation>
16	</author>
17
18	<PubDate>v2.1 $Date: 2002/11/28 14:38:00 $</PubDate>
19
20	<Abstract>
21	<para>
22	<blockquote>
23	<LITERALLAYOUT>
24	It is a book about a Spanish guy called Manual. You should read it.
25	-- Dilbert
26	</LITERALLAYOUT>
27
28	</BLOCKQUOTE>
29	</para>
30	</Abstract>
31
32
33	</BookInfo>
34
35	<Chapter id="powerdns">
36	<Title>The PowerDNS dynamic nameserver</Title>
37
38	<Para>
39	The PowerDNS daemon is a versatile nameserver which supports a large number
40	of backends. These backends can either be <link linkend="bindbackend">plain zonefiles</link> or be
41	<link linkend="pipebackend">more dynamic</link> in nature.
42	</Para>
43
44	<Para>
45	Prime examples of backends include relational databases, but also
46	loadbalancing and failover algorithms.
47	</Para>
48	<para>
49	The company is called PowerDNS BV, the nameserver daemon is called PDNS.
50	</para>
51
52	<sect1 id="function-design"><title>Function & design of PDNS</title>
53	<para>
54	PDNS is an authoritative only nameserver. It will answer questions about domains it knows about,
55	but will not go out on the net to resolve queries about other domains. However, it can use a
56	<link linkend="recursion">recursing backend</link> to provide that functionality.
57	</para>
58	<para>
59	When PDNS answers a question, it comes out of the database, and can be trusted as being authoritative. There is
60	no way to pollute the cache or to confuse the daemon.
61	</para>
62	<para>
63	PDNS has been designed to serve both the needs of small installations by being easy to setup, as well as
64	for serving very large query volumes on large numbers of domains.
65	</para>
66	<para>
67	Another prime goal is <link linkend="security">security</link>. By the use of language features, the PDNS source code
68	is very small (in the order of 10.000 lines) which makes auditing easy. In the same way, library features have been used
69	to mitigate the risks of buffer overflows.
70	</para>
71	<para>
72	Finally, PDNS is able to give a lot of <link linkend="monitoring">statistics</link> on its operation which is both helpful in
73	determining the scalability of an installation as well as for spotting problems.
74	</para>
75	</sect1>
76	<sect1 id="about"><title>About this document</title>
77	<para>
78	If you are reading this document from disk, you may want to check <ulink url="http://doc.powerdns.com">http://doc.powerdns.com</ulink>
79	for updates. The PDF version is available on <ulink url="http://doc.powerdns.com/pdf">http://doc.powerdns.com/pdf</ulink>, a text file is
80	on <ulink url="http://doc.powerdns.com/txt">http://doc.powerdns.com/txt/</ulink>.
81	</para>
82	<sect1 id="changelog">
83	<title>Release notes</title>
84	<para>
85	Before proceeding, it is advised to check the release notes for your PDNS version, as specified in the name of the distribution
86	file.
87	</para>
88	<sect2 id="changelog-2-9"><title>Version 2.9</title>
89	<para>
90	Open source release. Do not deploy unless you know what you are
91	doing. Stability is expected to return with 2.9.1, as are the binary builds.
92	</para>
93	<para>
94	<itemizedlist>
95	<listitem>
96	<para>
97	License changed to the GNU General Public License version 2.
98	</para>
99	</listitem>
100	<listitem>
101	<para>
102	Cleanups by Erik Bos @ xs4all.
103	</para>
104	</listitem>
105	<listitem>
106	<para>
107	Build improvements by Wichert Akkerman
108	</para>
109	</listitem>
110	<listitem>
111	<para>
112	Lots of work on the build system, entirely revamped. By PowerDNS.
113	</para>
114	</listitem>
115	</itemizedlist>
116	</sect2>
117
118	<sect2 id="changelog-2-8"><title>Version 2.8</title>
119	<para>
120	From this release onwards, we'll concentrate on stabilising for the 3.0 release. So if you have any must-have features,
121	let us know soonest. The 2.8 release fixes a bunch of small stability issues and add two new features. In the spirit of the move to
122	stability, this release has already been running 24 hours on our servers before release.
123	</para>
124	<para>
125	<itemizedlist>
126	<listitem>
127	<para>
128	pipe backend gains the ability to restricts its invocation to a limited number of requests. This allows a very busy nameserver
129	to still serve packets from a slow perl backend.
130	</para>
131	</listitem>
132	<listitem>
133	<para>
134	pipe backend now honors query-logging, which also documents which queries were blocked by the regex.
135	</para>
136	</listitem>
137	<listitem>
138	<para>
139	pipe backend now has its own backend chapter.
140	</para>
141	</listitem>
142	<listitem>
143	<para>
144	An incoming AXFR timeout at the wrong moment had the ability to crash the binary, forcing a reload. Thanks to our bug spotting
145	champions Mike Benoit and Simon Kirby of NetNation for reporting this.
146	</para>
147	</listitem>
148	</itemizedlist>
149	</para>
150	</sect2>
151	<sect2 id="changelog-2-7"><title>Version 2.7 and 2.7.1</title>
152	<para>
153	This version fixes some very long standing issues and adds a few new features. If you are still running 2.6, upgrade yesterday. If you
154	were running 2.6.1, an upgrade is still strongly advised.
155	</para>
156	<para>
157	Features:
158	<itemizedlist>
159	<listitem>
160	<para>
161	The controlsocket is now readable and writable by the 'setgid' user. This allows for non-root
162	access to PDNS which is nice for mrtg or cricket graphs.
163	</para>
164	</listitem>
165	<listitem>
166	<para>
167	MySQL backend (the non-generic one) gains the ability to read from a different table using the
168	<command>mysql-table</command> setting.
169	</para>
170	</listitem>
171	<listitem>
172	<para>
173	pipe backend now has a configurable timeout using the <command>pipe-timeout</command> setting. Thanks fo Steve Bromwich
174	for pointing out the need for this.
175	</para>
176	</listitem>
177	<listitem>
178	<para>
179	Experimental backtraces. If PowerDNS crashes, it will log a lot of numbers and sometimes more to the syslog.
180	If you see these, please report them to us. Only available under Linux.
181	</para>
182	</listitem>
183	</itemizedlist>
184	</para>
185	<para>
186	Bugs:
187	<itemizedlist>
188	<listitem>
189	<para>
190	2.7 briefly broke the mysql backend, so don't use it if you use that. 2.7.1 fixes this.
191	</para>
192	</listitem>
193	<listitem>
194	<para>
195	SOA records could sometimes have the wrong TTL. Thanks to Jonas Daugaard for reporting this.
196	</para>
197	</listitem>
198	<listitem>
199	<para>
200	An ANY query might lead to duplicate SOA records being returned under exceptional circumstances.
201	Thanks to Jonas Daugaard for reporting this.
202	</para>
203	</listitem>
204	<listitem>
205	<para>
206	Underlying the above bug, packet compression could sometimes suddenly be turned off, leading to
207	overly large responses and non-removal of duplicate records.
208	</para>
209	</listitem>
210	<listitem>
211	<para>
212	The <command>allow-axfr-ips</command> setting did not accept IP ranges (1.2.3.0/24) which the
213	documentation claimed it did (thanks to Florus Both of Ascio technologies for being sufficiently persistent in reporting this).
214	</para>
215	</listitem>
216	<listitem>
217	<para>
218	Killed backends were not being respawned, leading to suboptimal behaviour on intermittent database errors. Thanks to Steve Bromwich for
219	reporting this.
220	</para>
221	</listitem>
222	<listitem>
223	<para>
224	Corrupt packets during an incoming AXFR when acting as a slave would cause a PowerDNS reload instead of just failing that AXFR.
225	Thanks to Mike Benoit and Simon Kirby of NetNation for reporting this.
226	</para>
227	</listitem>
228	<listitem>
229	<para>
230	Label compression in incoming AXFR had problems with large offsets, causing the above mentioned errors. Thanks to Mike Benoit
231	and Simon Kirby of NetNation for reporting this.
232	</para>
233	</listitem>
234	</itemizedlist>
235	</para>
236	</sect2>
237
238	<sect2 id="changelog-2-6-1"><title>Version 2.6.1</title>
239	<para>
240	Quick fix release for a big cache problem.
241	</para>
242	</sect2>
243	<sect2 id="changelog-2-6"><title>Version 2.6</title>
244	<para>
245	Performance release. A lot of work has been done to raise PDNS performance to staggering levels in order to take part
246	in benchmarketing efforts. Together with our as yet unnamed partner, PDNS has been benchmarked at 60.000 mostly cached queries/second
247	on off the shelf PC hardware. Uncached performance was 17.000 uncached DNS queries/second on the .ORG domain.
248	</para>
249	<para>
250	Performance has been increased by both making PDNS itself quicker but also by lowering the number of backend queries typically needed. Operators
251	will typically see PDNS taking less CPU and the backend seeing less load.
252	</para>
253	<para>
254	Furthermore, some real bugs were fixed. A couple of undocumented performance switches may appear in --help output but you are advised to stay
255	away from these.
256	</para>
257	<para>
258	Developers: this version needs the pdns-2.5.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
259	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
260	</para>
261	<para>
262	Performance:
263	<itemizedlist>
264	<listitem>
265	<para>
266	A big error in latency calculations - cached packets were weighed 50 times less, leading to inflated latency reporting. Latency calculations
267	are now correct and way lower - often in the microseconds range.
268	</para>
269	</listitem>
270	<listitem>
271	<para>
272	It is now possible to run with 0 second cache TTLs. This used to cause very frequent cache cleanups, leading
273	to performance degradation.
274	</para>
275	</listitem>
276	<listitem>
277	<para>
278	Many tiny performance improvements, removing duplicate cache key calculations, etc. The cache itself has also been reworked
279	to be more efficient.
280	</para>
281	</listitem>
282	<listitem>
283	<para>
284	First 'CNAME' backend query replaced by an 'ANY' query, which most of the time returns the actual record,
285	preventing the need for a separate CNAME lookup, halving query load.
286	</para>
287	</listitem>
288	<listitem>
289	<para>
290	Much of the same for same-level-NS records on queries needing delegation.
291	</para>
292	</listitem>
293	</itemizedlist>
294	</para>
295	<para>
296	Bugs fixed:
297	<itemizedlist>
298	<listitem>
299	<para>
300	Incidentally, the cache count would show 'unknown' packets, which was harmless but confusing. Thanks to Mike and Simon of
301	NetNation for reporting this.
302	</para>
303	</listitem>
304	<listitem>
305	<para>
306	SOA hostmaster with a . in the local-part would be cached wrongly, leading to a stray backslash
307	in case of multiple successively SOA queries. Thanks to Ascio Techologies for spotting this bug.
308	</para>
309	</listitem>
310	<listitem>
311	<para>
312	zone2sql did not parse Verisign zonefiles correctly as these contained a $TTL statement in mid-record.
313	</para>
314	</listitem>
315	<listitem>
316	<para>
317	Sometimes packets would not be accounted, leading to 'udp-queries' and 'udp-answers' divergence.
318	</para>
319	</listitem>
320	</itemizedlist>
321	</para>
322	<para>
323	Features:
324	<itemizedlist>
325	<listitem>
326	<para>
327	'cricket' command added to init.d scripts that provides unadorned output for parsing by 'Cricket'.
328	</para>
329	</listitem>
330	</itemizedlist>
331	</para>
332	</sect2>
333	<sect2 id="changelog-2-5-1"><title>Version 2.5.1</title>
334	<para>
335	<ulink url="http://www.tuxedo.org/~esr/jargon/html/entry/brown-paper-bag-bug.html">Brown paper bag</ulink> release fixing
336	a huge memory leak in the new Query Cache.
337	</para>
338	<para>
339	Developers: this version needs the new pdns-2.5.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
340	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
341	</para>
342	<para>
343	And some small changes:
344	<itemizedlist>
345	<listitem>
346	<para>
347	Added support for RFC2038 compliant negative-answer caching. This allows remotes to cache the fact that
348	a domain does not exist and will not exist for a while. Thanks to Chris Thompson for <ulink url="http://ops.ietf.org/lists/namedroppers/namedroppers.2002/msg01697.html">pointing out how tiny our minds are</ulink>. This feature may cause a noticeable reduction
349	in query load.
350	</para>
351	</listitem>
352	<listitem>
353	<para>
354	Small speedup to non-packet-cached queries, incidentally fixing the huge memory leak.
355	</para>
356	</listitem>
357	<listitem>
358	<para>
359	<command>pdns_control ccounts</command> command outputs statistics on what is in the cache, which is
360	useful to help optimize your caching strategy.
361	</para>
362	</listitem>
363	</itemizedlist>
364	</para>
365	</sect2>
366	<sect2 id="changelog-2-5"><title>Version 2.5</title>
367	<para>
368	An important release which has seen quite a lot of trial and error testing. As a result, PDNS can now run with a huge cache
369	and concurrent invalidations. This is useful when running of a slower database or under high traffic load with a fast database.
370	</para>
371	<para>
372	Furthermore, the gpgsql2 backend has been validated for use and will soon supplant the gpgsql backend entirely. This also bodes
373	well for the gmysql backend which is the same code.
374	</para>
375	<para>
376	Also, a large amount of issues biting large scale slave operators were addressed. Most of these issues would only show up
377	after prolonged uptime.
378	</para>
379	<para>
380	New features:
381	<itemizedlist>
382	<listitem>
383	<para>
384	Query cache. The old Packet Cache only cached entire questions and their answers. This is very CPU efficient but
385	does not lead to maximum hitrate. Two packets both needing to resolve smtp.you.com internally would not benefit
386	from any caching. Furthermore, many different DNS queries lead to the same backend queries, like 'SOA for .COM?'.
387	</para>
388	<para>
389	PDNS now also caches backend queries, but only those having no answer (the majority) and those having one answer
390	(almost the rest).
391	</para>
392	<para>
393	In tests, these additional caches appear to halve the database backend load numerically and perhaps even more in terms
394	of CPU load. Often, queries with no answer are more expensive than those having one.
395	</para>
396	<para>
397	The default <command>ttl</command>s for the query-cache and negquery-cache are set to safe values (20 and 60 seconds
398	respectively), you should be seeing an improvement in behaviour without sacrificing a lot in terms of quick updates.
399	</para>
400	<para>
401	The webserver also displays the efficiency of the new Query Cache.
402	</para>
403	<para>
404	The old Packet Cache is still there (and useful) but see <xref linkend="performance"> for more details.
405	</para>
406	</listitem>
407	<listitem>
408	<para>
409	There is now the ability to shut off some logging at a very early stage. High performance sites doing thousands of
410	queries/second may in fact spend most of their CPU time on attempting to write out logging, even though it is ignored
411	by syslog. The new flag <command>log-dns-details</command>, on by default, allows the operator to kill most
412	informative-only logging before it takes any cpu.
413	</para>
414	</listitem>
415	<listitem>
416	<para>
417	Flags which can be switched 'on' and 'off' can now also be set to 'off' instead of only to 'no' to turn them off.
418	</para>
419	</listitem>
420	</itemizedlist>
421	</para>
422	<para>
423	Enhancements:
424	<itemizedlist>
425	<listitem>
426	<para>
427	Packet Cache is now case insensitive, leading to a higher hitrate because identical queries only differing in case
428	now both match. Care is taken to restore the proper case in the answer sent out.
429	</para>
430	</listitem>
431	<listitem>
432	<para>
433	Packet Cache stores packets more efficiently now, savings are estimated at 50%.
434	</para>
435	</listitem>
436	<listitem>
437	<para>
438	The Packet Cache is now asynchronous which means that PDNS continues to answer questions while the cache
439	is busy being purged or queried. Incidentally this will mean a cache miss where previously the question would
440	wait until the cache became available again.
441	</para>
442	<para>
443	The upshot of this is that operators can call <command>pdns_control purge</command> as often as desired without
444	fearing performance loss. Especially the full, non-specific, purge was speeded up tremendously.
445	</para>
446	<para>
447	This optimization is of little merit for small sites but is very important when running with a large packetcache, such
448	as when using recursion under high load.
449	</para>
450	</listitem>
451	<listitem>
452	<para>
453	AXFR log messages now all contain the word 'AXFR' to ease grepping.
454	</para>
455	</listitem>
456	<listitem>
457	<para>
458	Linux static version now compiled with gcc 3.2 which is known to output better and faster code than the previously
459	used 3.0.4.
460	</para>
461	</listitem>
462	</itemizedlist>
463	</para>
464	<para>
465	Bugs fixed:
466	<itemizedlist>
467	<listitem>
468	<para>
469	Packetcache would sometimes send packets back with slightly modified flags if these differed from the flags
470	of the cached copy.
471	</para>
472	</listitem>
473	<listitem>
474	<para>
475	Resolver code did bad things with filedescriptors leading to fd exhaustion after prolonged uptimes and many slave
476	SOA currency checks.
477	</para>
478	</listitem>
479	<listitem>
480	<para>
481	Resolver code failed to properly log some errors, leading to operator uncertainty regarding to AXFR problems with
482	remote masters.
483	</para>
484	</listitem>
485	<listitem>
486	<para>
487	After prolonged uptime, slave code would try to use privileged ports for originating queries, leading to bad
488	replication efficiency.
489	</para>
490	</listitem>
491	<listitem>
492	<para>
493	Masters sending back answers in differing case from questions would lead to bogus
494	'Master tried to sneak in out-of-zone data' errors and failing AXFRs.
495	</para>
496	</listitem>
497	</itemizedlist>
498	</para>
499	</sect2>
500	<sect2 id="changelog-2-4"><title>Version 2.4</title>
501	<para>
502	Developers: this version is compatible with the pdns-2.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
503	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
504	</para>
505	<para>
506	This version fixes some stability issues with malformed or malcrafted packets. An upgrade is advised. Furthermore, there are interesting new
507	features.
508	</para>
509	<para>
510	New features:
511	</para>
512	<para>
513	<itemizedlist>
514	<listitem>
515	<para>
516	Recursive queries are now also cached, but in a separate namespace so non-recursive queries don't get recursed answers and
517	vice versa. This should mean way lower database load for sites running with the current default lazy-recursion. Up to now,
518	each and every recursive query would lead to a large amount of SQL queries.
519	</para>
520	<para>
521	To prevent the packetcache from becoming huge, a separate <command>recursive-cache-ttl</command> can be specified.
522	</para>
523	</listitem>
524	<listitem>
525	<para>
526	The ability to change parameters at runtime was added. Currently, only the new <command>query-logging</command> flag
527	can be changed.
528	</para>
529	</listitem>
530	<listitem>
531	<para>
532	Added <command>query-logging</command> flag which hints a backend that it should output a textual representation of queries
533	it receives. Currently only gmysql and gpgsql2 honor this flag.
534	</para>
535	</listitem>
536	<listitem>
537	<para>
538	Gmysql backend can now also talk to PgSQL, leading to less code. Currently, the old postgresql driver ('gpgsql') is still the default,
539	the new driver is available as 'gpgsql2' and has the benefit that it does query logging. In the future, gpgsql2 will become the default
540	gpgsql driver.
541	</para>
542	</listitem>
543	<listitem>
544	<para>
545	DNS recursing proxy is now more verbose in logging odd events which may be caused by buggy recursing backends.
546	</para>
547	</listitem>
548	<listitem>
549	<para>
550	Webserver now displays peak queries/second 1 minute average.
551	</para>
552	</listitem>
553	</itemizedlist>
554	</para>
555	<para>
556	Bugs fixed:
557	<itemizedlist>
558	<listitem>
559	<para>
560	Failure to connect to database in master/slave communicator thread could lead to an unclean reload, fixed.
561	</para>
562	</listitem>
563	</itemizedlist>
564	<para>
565	Documentation: added details for <command>strict-rfc-axfrs</command>. This feature can be used if very old clients need to be able
566	to do zone transfers with PDNS. Very slow.
567	</para>
568
569	</sect2>
570	<sect2 id="changelog-2-3"><title>Version 2.3</title>
571	<para>
572	Developers: this version is compatible with the pdns-2.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
573	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
574	</para>
575	<para>
576	This release adds the Generic MySQL backend which allows full master/slave semantics with MySQL and InnoDB tables (or other tables that support
577	transactions). See <xref linkend="generic-mypgsql-backends">.
578	</para>
579	<para>
580	Other new features:
581	</para>
582	<para>
583	<itemizedlist>
584	<listitem>
585	<para>
586	Improved error messages in master/slave communicator will help down track problems.
587	</para>
588	</listitem>
589	<listitem>
590	<para>
591	<command>slave-cycle-interval</command> setting added. Very large sites with thousands of slave domains may need to raise this value
592	above the default of 60. Every cycle, domains in undeterminate state are checked for their condition. Depending on the health of the masters,
593	this may entail many SOA queries or attempted AXFRs.
594	</para>
595	</listitem>
596	</itemizedlist>
597	</para>
598	<para>
599	Bugs fixed:
600	</para>
601	<para>
602	<itemizedlist>
603	<listitem>
604	<para>
605	'pdns_control purge <userinput>domain</userinput>' and 'pdns_control purge <userinput>domain$</userinput>' were broken in version 2.2 and
606	did not in fact purge the cache. There is a slight risk that domain-specific purge commands could force a reload in previous version.
607	Thanks to Mike Benoit of NetNation for discovering this.
608	</para>
609	</listitem>
610	<listitem>
611	<para>
612	Master/slave communicator thread got confused in case of delayed answers from slow masters. While not causing harm, this caused inefficient
613	behaviour when testing large amounts of slave domains because additional 'cycles' had to pass before all domains would have their status
614	ascertained.
615	</para>
616	</listitem>
617	<listitem>
618	<para>
619	Backends implementing special SOA semantics (currently only the undocumented 'pdns express backend', or homegrown backends) would
620	under some circumstances not answer the SOA record in case of an ANY query. This should put an end to the last DENIC problems. Thanks to
621	DENIC for helping us find the problem.
622	</para>
623	</listitem>
624	</itemizedlist>
625	</para>
626	</sect2>
627	<sect2 id="changelog-2-2"><title>Version 2.2</title>
628	<para>
629	Developers: this version is compatible with the pdns-2.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
630	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
631	</para>
632	<para>
633	Again a big release. PowerDNS is seeing some larger deployments in more demanding environments and these are helping shake out remaining issues,
634	especially with recursing backends.
635	</para>
636	<para>
637	The big news is that wildcard CNAMEs are now supported, an oft requested feature and nearly the only part in which PDNS differed from BIND in
638	authoritative capabilities.
639	</para>
640	<para>
641	If you were seeing signal 6 errors in PDNS causing reloads and intermittent service disruptions, please upgrade to this version.
642	</para>
643	<para>
644	For operators of PowerDNS Express trying to host .DE domains, the very special <command>soa-serial-offset</command> feature has been added
645	to placate the new DENIC requirement that the SOA serial be at least six digits. PowerDNS Express uses the SOA serial as an actual serial and
646	not to insert dates and hence often has single digit soa serial numbers, causing big problems with .DE redelegations.
647	</para>
648	<para>
649	Bugs fixed:
650	<itemizedlist>
651	<listitem>
652	<para>
653	Malformed or shortened TCP recursion queries would cause a signal 6 and a reload. Same for EOF from the TCP recursing backend.
654	Thanks to Simon Kirby and Mike Benoit of NetNation for helping debug this.
655	</para>
656	</listitem>
657	<listitem>
658	<para>
659	Timeouts on the TCP recursing backend were far too long, leading to possible exhaustion of TCP resolving threads.
660	</para>
661	</listitem>
662	<listitem>
663	<para>
664	<command>pdns_control purge domain</command> accidentally cleaned all packets with that name as a prefix. Thanks to Simon Kirby
665	for spotting this.
666	</para>
667	</listitem>
668	<listitem>
669	<para>
670	Improved exception error logging - in some circumstances PDNS would not properly log the cause of an exception, which hampered problem
671	resolution.
672	</para>
673	</listitem>
674	</itemizedlist>
675	</para>
676	<para>
677	New features:
678	<itemizedlist>
679	<listitem>
680	<para>
681	Wildcard CNAMEs now work as expected!
682	</para>
683	</listitem>
684	<listitem>
685	<para>
686	<command>pdns_control purge</command> can now also purge based on suffix, allowing operators to
687	purge an entire domain from the packet cache instead of only specific records. See also <xref linkend="pdnscontrol">
688	Thanks to Mike Benoit for this suggestion.
689	</para>
690	</listitem>
691	<listitem>
692	<para>
693	<command>soa-serial-offset</command> for installations with small SOA serial numbers wishing to register .DE domains
694	with DENIC which demands six-figure SOA serial numbers. See also <xref linkend="all-settings">.
695	</para>
696	</listitem>
697	</itemizedlist>
698	</para>
699	</sect2>
700	<sect2 id="changelog-2-1"><title>Version 2.1</title>
701	<para>
702	This is a somewhat bigger release due to pressing demands from customers. An upgrade is advised for installations using Recursion.
703	If you are using recursion, it is vital that you are aware of changes in semantics. Basically, local data will now override data in your
704	recursing backend under most circumstances. Old behaviour can be restored by turning <command>lazy-recursion</command> off.
705	</para>
706	<para>
707	Developers: this version has a new pdns-2.1 development kit, available on <ulink url="http://downloads.powerdns.com/releases/dev">
708	http://downloads.powerdns.com/releases/dev</ulink>. See also <xref linkend="backend-writers-guide">.
709	</para>
710	<para>
711	<warning>
712	<para>
713	Most users will run a static version of PDNS which has no dependencies on external libraries. However, some may need to run the dynamic version.
714	This warning applies to these users.
715	</para>
716	<para>
717	To run the dynamic version of PDNS, which is needed for backend drivers which are only available in source form, gcc 3.0 is required.
718	RedHat 7.2 comes with gcc 3.0 as an optional component, RedHat 7.3 does not. However, the RedHat 7.2 Update gcc rpms install just fine
719	on RedHat 7.3. For Debian, we suggest running 'woody' and installing the g++-3.0 package. We expect to release a FreeBSD dynamic version
720	shortly.
721	</para>
722	</warning>
723	</para>
724
725	<para>
726	Bugs fixed:
727	<itemizedlist>
728	<listitem>
729	<para>
730	RPM releases sometimes overwrote previous configuration files. Thanks to Jorn Ekkelenkamp of Hubris/ISP Services for reporting this.
731	</para>
732	</listitem>
733	<listitem>
734	<para>
735	TCP recursion sent out overly large responses due to a byteorder mistake, confusing some clients. Thanks to the capable engineers
736	of NetNation for bringing this to our attention.
737	</para>
738	</listitem>
739	<listitem>
740	<para>
741	TCP recursion in combination with a recursing backend on a non-standard port did not work, leading to a
742	non-functioning TCP listener. Thanks to the capable engineers of NetNation for bringing this to our attention.
743	</para>
744	</listitem>
745	</itemizedlist>
746	</para>
747	<para>
748	Unexpected behaviour:
749	<itemizedlist>
750	<listitem>
751	<para>
752	Wildcard URL records where not implemented because they are a performance penalty. To turn these on, enable
753	<command>wildcard-url</command> in the configuration.
754	</para>
755	</listitem>
756	<listitem>
757	<para>
758	Unlike other nameservers, local data did not override the internet for recursing queries. This has mostly been brought into conformance
759	with user expectations. If a recursive question can be answered entirely from local data, it is. To restore old behaviour, disable
760	<command>lazy-recursion</command>. Also see <xref linkend="recursion">.
761	</para>
762	</listitem>
763	</itemizedlist>
764	</para>
765	<para>
766	Features:
767	<itemizedlist>
768	<listitem>
769	<para>
770	Oracle support has been tuned, leading to the first public release of the Oracle backend. Zone2sql now outputs better SQL
771	and the backend is now fully documented. Furthermore, the queries are compatible with the PowerDNS XML-RPC product, allowing
772	PowerDNS express to run off Oracle. See <xref linkend="oracle">.
773	</para>
774	</listitem>
775	<listitem>
776	<para>
777	Zone2sql now accepts --transactions to wrap zones in a transaction for PostgreSQL and Oracle output. This is a major speedup and also
778	makes for better isolation of inserts. See <xref linkend="zone2sql">.
779	</para>
780	</listitem>
781	<listitem>
782	<para>
783	<command>pdns_control</command> now has the ability to purge the PowerDNS cache or parts of it. This enables operators to
784	raise the TTL of the Packet Cache to huge values and only to invalidate the cache when changes are made. See also <xref linkend="performance"> and
785	<xref linkend="pdnscontrol">.
786	</para>
787	</listitem>
788	</itemizedlist>
789	</para>
790	</sect2>
791	<sect2 id="changelog-2-0-1"><title>Version 2.0.1</title>
792	<para>
793	Maintenance release, fixing three small issues.
794	</para>
795	<para>
796	Developers: this version is compatible with 1.99.11 backends.
797	</para>
798	<para>
799	<itemizedlist>
800	<listitem>
801	<para>
802	PowerDNS ignored the <command>logging-facility</command> setting unless it was specified on the commandline.
803	Thanks to Karl Obermayer from WebMachine Technologies for noticing this.
804	</para>
805	</listitem>
806	<listitem>
807	<para>
808	Zone2sql neglected to preserve 'slaveness' of domains when converting to the slave capable PostgreSQL backend. Thanks
809	to Mike Benoit of NetNation for reporting this. Zone2sql now has a <command>--slave</command> option.
810	</para>
811	</listitem>
812	<listitem>
813	<para>
814	SOA Hostmaster addresses with dots in them before the @-sign were mis-encoded on the wire.
815	</para>
816	</listitem>
817	</itemizedlist>
818	</para>
819	</sect2>
820	<sect2 id="changelog-2-0"><title>Version 2.0</title>
821	<para>
822	Two bugfixes, one stability/security related. No new features.
823	</para>
824	<para>
825	Developers: this version is compatible with 1.99.11 backends.
826	</para>
827	<para>
828	Bugfixes:
829	</para>
830	<para>
831	<itemizedlist>
832	<listitem>
833	<para>
834	zone2sql refused to work under some circumstances, taking 100% cpu and not functioning. Thanks to Andrew Clark and Mike Benoit
835	for reporting this.
836	</para>
837	</listitem>
838	<listitem>
839	<para>
840	Fixed a stability issue where malformed packets could force PDNS to reload. Present in all earlier 2.0 versions.
841	</para>
842	</listitem>
843	</itemizedlist>
844	</para>
845	</sect2>
846	<sect2 id="changelog-2-0-rc2"><title>Version 2.0 Release Candidate 2</title>
847	<para>
848	Mostly bugfixes, no really new features.
849	</para>
850	<para>
851	Developers: this version is compatible with 1.99.11 backends.
852	</para>
853	<para>
854	Bugs fixed:
855	</para>
856	<para>
857	<itemizedlist>
858	<listitem>
859	<para>
860	chroot() works again - 2.0rc1 silently refused to chroot. Thanks to Hub Dohmen for noticing this.
861	</para>
862	</listitem>
863	<listitem>
864	<para>
865	setuid() and setgid() security features were silently not being performed in 2.0rc1. Thanks to Hub Dohmen for noticing this.
866	</para>
867	</listitem>
868	<listitem>
869	<para>
870	MX preferences over 255 now work as intended. Thanks to Jeff Crowe for noticing this.
871	</para>
872	</listitem>
873	<listitem>
874	<para>
875	IPv6 clients can now also benefit from the recursing backend feature. Thanks to Andy Furnell for proving beyond any doubt that this
876	did not work.
877	</para>
878	</listitem>
879	<listitem>
880	<para>
881	Extremely bogus code removed from DNS notification reception code - please test! Thanks to Jakub Jermar for working with us
882	in figuring out just how broken this was.
883	</para>
884	</listitem>
885	<listitem>
886	<para>
887	AXFR code improved to handle more of the myriad different zonetransfer dialects available. Specifically, interoperability
888	with Bind 4 was improved, as well as Bind 8 in 'strict rfc conformance' mode. Thanks again for Jakub Jermar for running many tests for us.
889	If your transfers failed with 'Unknown type 14!!' or words to that effect, this was it.
890	</para>
891	</listitem>
892	</itemizedlist>
893	</para>
894	<para>
895	Features:
896	<itemizedlist>
897	<listitem>
898	<para>
899	Win32 version now has a zone2sql tool.
900	</para>
901	</listitem>
902	<listitem>
903	<para>
904	Win32 version now has support for specifying how urgent messages should be before they go to the NT event log.
905	</para>
906	</listitem>
907	</itemizedlist>
908	</para>
909	<para>
910	Remaining issues:
911	<itemizedlist>
912	<listitem>
913	<para>
914	One persistent report of the default 'chroot=./' configuration not working.
915	</para>
916	</listitem>
917	<listitem>
918	<para>
919	One report of disable-axfr and allow-axfr-ips not working as intended.
920	</para>
921	</listitem>
922	<listitem>
923	<para>
924	Support for relative paths in zones and in Bind configuration is not bug-for-bug compatible with bind yet.
925	</para>
926	</listitem>
927	</itemizedlist>
928	</para>
929	</sect2>
930	<sect2 id="changelog-2-0-rc1"><title>Version 2.0 Release Candidate 1</title>
931	<para>
932	The MacOS X release! A very experimental OS X 10.2 build has been added. Furthermore, the Windows version is now in line with Unix with
933	respect to capabilities. The ODBC backend now has the code to function as both a master and a slave.
934	</para>
935	<para>
936	Developers: this version is compatible with 1.99.11 backends.
937	</para>
938	<para>
939	<itemizedlist>
940	<listitem>
941	<para>
942	Implemented native packet response parsing code, allowing Windows to perform AXFR and NS and SOA queries.
943	</para>
944	</listitem>
945	<listitem>
946	<para>
947	This is the first version for which we have added support for Darwin 6.0, which is part of the forthcoming Mac OS X 10.2.
948	Please note that although this version is marked RC1, that we have not done extensive testing yet. Consider this a technology
949	preview.
950	</para>
951	<para>
952	<itemizedlist>
953	<listitem><para>
954	The Darwin version has been developed on Mac OS X 10.2 (6C35). Other versions may or may not work.
955	</para></listitem>
956	<listitem><para>
957	Currently only the random, bind, mysql and pdns backends are included.
958	</para></listitem>
959
960	<listitem><para>
961	The menu based installer script does not work, you will have to edit pathconfig by hand as outlined in chapter 2.
962	</para></listitem>
963
964	<listitem><para>
965	On Mac OS X Client, PDNS will fail to start because a system service is already bound to port 53.
966	</para></listitem>
967	</itemizedlist>
968	</para>
969	<para>
970	This version is distributed as a compressed tar file. You should follow the generic UNIX installation instructions.
971	</para>
972	</listitem>
973	</itemizedlist>
974	</para>
975	<para>
976	Bugs fixed:
977	<itemizedlist>
978	<listitem>
979	<para>
980	Zone2sql PostgreSQL mode neglected to lowercase $ORIGIN. Thanks to Maikel Verheijen of Ladot for spotting this.
981	</para>
982	</listitem>
983	<listitem>
984	<para>
985	Zone2sql PostgreSQL mode neglected to remove a trailing dot from $ORIGIN if present.
986	Thanks to Thanks to Maikel Verheijen of Ladot for spotting this.
987	</para>
988	</listitem>
989	<listitem>
990	<para>
991	Zonefile parser was not compatible with bind when $INCLUDING non-absolute filenames. Thanks to Jeff Miller for working out
992	how this should work.
993	</para>
994	</listitem>
995	<listitem>
996	<para>
997	Bind configuration parser was not compatible with bind when including non-absolute filenames. Thanks to Jeff Miller for working out
998	how this should work.
999	</para>
1000	</listitem>
1001	<listitem>
1002	<para>
1003	Documentation incorrectly listed the Bind backend as 'slave capable'. This is not yet true, now labeled 'experimental'.
1004	</para>
1005	</listitem>
1006	</itemizedlist>
1007	</para>
1008	<para>
1009	Windows changes. We are indebted to Dimitry Andric who educated us in the ways of distributing Windows software.
1010	<itemizedlist>
1011	<listitem>
1012	<para>
1013	<filename>pdns.conf</filename> is now read if available.
1014	</para>
1015	</listitem>
1016	<listitem>
1017	<para>
1018	Console version responds to ^c now.
1019	</para>
1020	</listitem>
1021	<listitem>
1022	<para>
1023	Default pdns.conf added to distribution
1024	</para>
1025	</listitem>
1026	<listitem>
1027	<para>
1028	Uninstaller missed several files, leaving remnants behind
1029	</para>
1030	</listitem>
1031
1032	<listitem>
1033	<para>
1034	DLLs are now installed locally, with the pdns executable.
1035	</para>
1036	</listitem>
1037
1038	<listitem>
1039	<para>
1040	pdns_control is now also available on Windows
1041	</para>
1042	</listitem>
1043	<listitem>
1044	<para>
1045	ODBC backend can now act as master and slave. Experimental.
1046	</para>
1047	</listitem>
1048	<listitem>
1049	<para>
1050	The example zone missed indexes and had other faults.
1051	</para>
1052	</listitem>
1053	<listitem>
1054	<para>
1055	A runtime DLL that is present on most windows systems (but not all!) was missing.
1056	</para>
1057	</listitem>
1058	</itemizedlist>
1059	</para>
1060	</sect2>
1061	<sect2 id="changelog-1-99-12"><title>Version 1.99.12 Prerelease</title>
1062	<para>
1063	The Windows release! See <xref linkend="windows">. Beware, windows support is still very fresh and untested. Feedback is very welcome.
1064	</para>
1065	<para>
1066	Developers: this version is compatible with 1.99.11 backends.
1067	</para>
1068	<para>
1069	<itemizedlist>
1070	<listitem>
1071	<para>
1072	Windows 2000 codebase merge completed. This resulted in quite some changes on the Unix end of things, so this may impact reliability
1073	</para>
1074	</listitem>
1075	<listitem>
1076	<para>
1077	ODBC backend added for Windows. See <xref linkend="odbc">.
1078	</para>
1079	</listitem>
1080	<listitem>
1081	<para>
1082	IBM DB2 Universal Database backend available for Linux. See <xref linkend="db2">.
1083	</para>
1084	</listitem>
1085	<listitem>
1086	<para>
1087	Zone2sql now understands $INCLUDE. Thanks to Amaze Internet for nagging about this
1088	</para>
1089	</listitem>
1090	<listitem>
1091	<para>
1092	The SOA Mininum TTL now has a configurable default (<command>soa-minimum-ttl</command>)value to placate the DENIC requirements.
1093	</para>
1094	</listitem>
1095	<listitem>
1096	<para>
1097	Added a limit on the simultaneous numbers of TCP connections to accept (<command>max-tcp-connections</command>). Defaults to 10.
1098	</para>
1099	</listitem>
1100	</itemizedlist>
1101	</para>
1102	<para>
1103	Bugs fixed:
1104	<itemizedlist>
1105	<listitem>
1106	<para>
1107	When operating in virtual hosting mode (See <xref linkend="virtual">), the additional init.d scripts would not function correctly
1108	and interface with other pdns instances.
1109	</para>
1110	</listitem>
1111	<listitem>
1112	<para>
1113	PDNS neglected to conserve case on answers. So a query for WwW.PoWeRdNs.CoM would get an answer listing the address of www.powerdns.com.
1114	While this did not confuse resolvers, it is better to conserve case. This has semantical concequences for all backends, which the documentation
1115	now spells out.
1116	</para>
1117	</listitem>
1118	<listitem>
1119	<para>
1120	PostgreSQL backend was case sensitive and returned only answers in case an exact match was found. The Generic PostgreSQL backend is now
1121	officially all lower case and zone2sql in PostgreSQL mode enforces this.
1122	Documentation has been been updated to reflect the case change. Thanks to Maikel Verheijen of Ladot for
1123	spotting this!
1124	</para>
1125	</listitem>
1126	<listitem>
1127	<para>
1128	Documentation bug - postgresql create/index statements created a duplicate index. If you've previously copy pasted the commands and
1129	not noticed the error, execute <command>CREATE INDEX rec_name_index ON records(name)</command> to remedy. Thanks to Jeff Miller for reporting
1130	this. This also lead to depressingly slow 'ANY' lookups for those of you doing benchmarks.
1131	</para>
1132	</listitem>
1133	</itemizedlist>
1134	</para>
1135	<para>
1136	Features:
1137	<itemizedlist>
1138	<listitem>
1139	<para>
1140	pdns_control (see <xref linkend="pdnscontrol">) now opens the local end of its socket in <filename>/tmp</filename> instead of next to the
1141	remote socket (by default <filename>/var/run</filename>). This eases the way for allowing non-root access to pdns_control. When running chrooted
1142	(see <xref linkend="security">), the local socket again moves back to <filename>/var/run</filename>.
1143	</para>
1144	</listitem>
1145	<listitem>
1146	<para>
1147	pdns_control now has a 'version' command. See <xref linkend="pdnscontrol">.
1148	</para>
1149	</listitem>
1150	</itemizedlist>
1151
1152	</sect2>
1153	<sect2 id="changelog-1-99-11"><title>Version 1.99.11 Prerelease</title>
1154	<para>
1155	This release is important because it is the first release which is accompanied by an Open Source Backend Development Kit, allowing external
1156	developers to write backends for PDNS. Furthermore, a few bugs have been fixed:
1157	</para>
1158	<para>
1159	<itemizedlist>
1160	<listitem>
1161	<para>
1162	Lines with only whitespace in zone files confused PDNS (thanks Henk Wevers)
1163	</para>
1164	</listitem>
1165	<listitem>
1166	<para>
1167	PDNS did not properly parse TTLs with symbolic sufixes in zone files, ie 2H instead of 7200 (thanks Henk Wevers)
1168	</para>
1169	</listitem>
1170	</itemizedlist>
1171	</para>
1172	</sect2>
1173	<sect2 id="changelog-1-99-10"><title>Version 1.99.10 Prerelease</title>
1174	<para>
1175	IMPORTANT: there has been a tiny license change involving free public webbased dns hosting, check out the changes before deploying!
1176	</para>
1177	<para>
1178	PDNS is now feature complete, or very nearly so. Besides adding features, a lot of 'fleshing out' work is done now. There is an important
1179	performance bug fix which may have lead to disappointing benchmarks - so if you saw any of that, please try either this version or 1.99.8 which
1180	also does not have the bug.
1181	</para>
1182	<para>
1183	This version has been very stable for us on multiple hosts, as was 1.99.9.
1184	</para>
1185	<para>
1186	PostgreSQL users should be aware that while 1.99.10 works with the schema as presented in earlier versions, advanced features
1187	such as master or slave support will not work unless you create the new 'domains' table as well.
1188	</para>
1189	<para>
1190	Bugs fixed:
1191	<itemizedlist>
1192	<listitem>
1193	<para>
1194	Wildcard AAAA queries sometimes received an NXDOMAIN error where they should have gotten an empty NO ERROR. Thanks to Jeroen Massar
1195	for spotting this on the .TK TLD!
1196	</para>
1197	</listitem>
1198	<listitem>
1199	<para>
1200	Do not disable the packetcache for 'recursion desired' packets unless a recursor was configured. Thanks to Greg Schueler for noticing this.
1201	</para>
1202	</listitem>
1203	<listitem>
1204	<para>
1205	A failing backend would not be reinstated. Thanks to 'Webspider' for discovering this problem with PostgreSQL connections that die after
1206	prolonged inactivity.
1207	</para>
1208	</listitem>
1209	<listitem>
1210	<para>
1211	Fixed loads of IPv6 transport problems. Thanks to Marco Davids and others for testing. Considered ready for production now.
1212	</para>
1213	</listitem>
1214
1215	<listitem>
1216	<para>
1217	<command>Zone2sql</command> printed a debugging statement on range $GENERATE commands. Thanks to Rene van Valkenburg for spotting this.
1218	</para>
1219	</listitem>
1220	</itemizedlist>
1221	</para>
1222	<para>
1223	Features:
1224	<itemizedlist>
1225	<listitem>
1226	<para>
1227	PDNS can now act as a master, sending out notifications in case of changes and allowing slaves to AXFR. Big rewording of replication support,
1228	domains are now either 'native', 'master' or 'slave'. See <xref linkend="replication"> for lots of details.
1229	</para>
1230	</listitem>
1231	<listitem>
1232	<para>
1233	<command>Zone2sql</command> in PostgreSQL mode now populates the 'domains' table for easy master, slave or native replication support.
1234	</para>
1235	</listitem>
1236	<listitem>
1237	<para>
1238	Ability to disable those annoying Windows DNS Dynamic Update messages from appearing in the log. See <function>log-failed-updates</function>
1239	in <xref linkend="all-settings">.
1240	</para>
1241	</listitem>
1242	<listitem>
1243	<para>
1244	Ability to run on IPv6 transport only
1245	</para>
1246	</listitem>
1247	<listitem>
1248	<para>
1249	Logging can now happen under a 'facility' so all PDNS messages appear in their own file. See <xref linkend="syslog">.
1250	</para>
1251	</listitem>
1252
1253	<listitem>
1254	<para>
1255	Different OS releases of PDNS now get different install path defaults. Thanks to Mark Lastdrager for nagging about this and to Nero Imhard and
1256	Frederique Rijsdijk for suggesting saner defaults.
1257	</para>
1258	</listitem>
1259	<listitem>
1260	<para>
1261	Infrastructure for 'also-notify' statements added.
1262	</para>
1263	</listitem>
1264
1265	</itemizedlist>
1266	</para>
1267	</sect2>
1268	<sect2 id="changelog-1-99-9"><title>Version 1.99.9 Early Access Prerelease</title>
1269	<para>
1270	This is again a feature and an infrastructure release. We are nearly feature complete and will soon start
1271	work on the backends to make sure that they are all master, slave and 'superslave' capable.
1272	</para>
1273	<para>
1274	Bugs fixed:
1275	<itemizedlist>
1276	<listitem>
1277	<para>
1278	PDNS sometimes sent out duplicate replies for packets passed to the recursing backend. Mostly a problem on SMP systems. Thanks to Mike Benoit
1279	for noticing this.
1280	</para>
1281	</listitem>
1282	<listitem>
1283	<para>
1284	Out-of-bailiwick CNAMES (ie, a CNAME to a domain not in PDNS) caused a 'ServFail' packet in 1.99.8, indicating failure, leading to hosts not
1285	resolving. Thanks to Martin Gillstrom for noticing this.
1286	</para>
1287	</listitem>
1288	<listitem>
1289	<para>
1290	Zone2sql balked at zones editted under operating sytems terminating files with ^Z (Windows). Thanks Brian Willcott for reporting this.
1291	</para>
1292	</listitem>
1293	<listitem>
1294	<para>
1295	PostgreSQL backend logged the password used to connect. Now only does so in case of failure to connect. Thanks to 'Webspider' for noticing this.
1296	</para>
1297	</listitem>
1298	<listitem>
1299	<para>
1300	Debian unstable distribution wrongly depended on home compiled PostgreSQL libraries. Thanks to Konrad Wojas for noticing this.
1301	</para>
1302	</listitem>
1303	</itemizedlist>
1304	</para>
1305	<para>
1306	Features:
1307	<itemizedlist>
1308	<listitem>
1309	<para>
1310	When operating as a slave, AAAA records are now supported in the zone. They were already supported in master zones.
1311	</para>
1312	</listitem>
1313	<listitem>
1314	<para>
1315	IPv6 transport support - PDNS can now listen on an IPv6 socket using the <command>local-ipv6</command> setting.
1316	</para>
1317	</listitem>
1318	<listitem>
1319	<para>
1320	Very silly randombackend added which appears in the documentation as a sample backend. See <xref linkend="backend-writers-guide">.
1321	</para>
1322	</listitem>
1323	<listitem>
1324	<para>
1325	When transferring a slave zone from a master, out of zone data is now rejected. Malicious operators might try to insert bad records otherwise.
1326	</para>
1327	</listitem>
1328	<listitem>
1329	<para>
1330	'Supermaster' support for automatic provisioning from masters. See <xref linkend="supermaster">.
1331	</para>
1332	</listitem>
1333	<listitem>
1334	<para>
1335	Recursing backend can now live on a non-standard (!=53) port. See <xref linkend="recursion">.
1336	</para>
1337	</listitem>
1338	<listitem>
1339	<para>
1340	Slave zone retrieval is now queued instead of immediate, which scales better and is more resilient to temporary failures.
1341	</para>
1342	</listitem>
1343	<listitem>
1344	<para>
1345	<command>max-queue-length</command> parameter. If this many packets are queued for database attention, consider the situation hopeless and
1346	respawn.
1347	</para>
1348	</listitem>
1349	</itemizedlist>
1350	</para>
1351	<para>
1352	Internal:
1353	<itemizedlist>
1354	<listitem>
1355	<para>
1356	SOA records are now 'special' and each backend can optionally generate them in special ways. PostgreSQL backend does so
1357	when operating as a slave.
1358	</para>
1359	</listitem>
1360	<listitem>
1361	<para>
1362	Writing backends is now a lot easier. See <xref linkend="backend-writers-guide">.
1363	</para>
1364	</listitem>
1365	<listitem>
1366	<para>
1367	Added Bindbackend to internal regression tests, confirming that it is compliant.
1368	</para>
1369	</listitem>
1370	</itemizedlist>
1371	</para>
1372	</sect2>
1373	<sect2 id="changelog-1-99-8"><title>Version 1.99.8 Early Access Prerelease</title>
1374	<para>
1375	A lot of infrastructure work gearing up to 2.0. Some stability bugs fixed and a lot of new features.
1376	</para>
1377	<para>
1378	Bugs fixed:
1379	<itemizedlist>
1380	<listitem>
1381	<para>
1382	Bindbackend was overly complex and crashed on some systems on startup. Simplified launch code.
1383	</para>
1384	</listitem>
1385	<listitem>
1386	<para>
1387	SOA fields were not always properly filled in, causing default values to go out on the wire
1388	</para>
1389	</listitem>
1390	<listitem>
1391	<para>
1392	Obscure bug triggered by malicious packets (we know who you are) in SOA finding code fixed.
1393	</para>
1394	</listitem>
1395	<listitem>
1396	<para>
1397	Magic serial number calculation contained a double free leading to instability.
1398	</para>
1399	</listitem>
1400	<listitem>
1401	<para>
1402	Standards violation, questions for domains for which PDNS was unauthoritative now get a SERVFAIL answer.
1403	Thanks to the IETF Namedroppers list for helping out with this.
1404	</para>
1405	</listitem>
1406	<listitem>
1407	<para>
1408	Slowly launching backends were being relaunched at a great rate when queries were coming in while launching backends.
1409	</para>
1410	</listitem>
1411	<listitem>
1412	<para>
1413	MySQL-on-unix-domain-socket on SMP systems was overwhelmed by the quick connection rate on launch, inserted a small 50ms delay.
1414	</para>
1415	</listitem>
1416	<listitem>
1417	<para>
1418	Some SMP problems appear to be compiler related. Shifted to GCC 3.0.4 for Linux.
1419	</para>
1420	</listitem>
1421	<listitem>
1422	<para>
1423	Ran ispell on documentation.
1424	</para>
1425	</listitem>
1426	</itemizedlist>
1427	</para>
1428	<para>
1429	Feature enhancements:
1430	<itemizedlist>
1431	<listitem>
1432	<para>
1433	Recursing backend. See <xref linkend="recursion">. Allows recursive and authoritative DNS on the same IP address.
1434	</para>
1435	</listitem>
1436	<listitem>
1437	<para>
1438	<link linkend="naptr">NAPTR support</link>, which is especially useful for the ENUM/E.164 community.
1439	</para>
1440	</listitem>
1441	<listitem>
1442	<para>
1443	Zone transfers can now be allowed per <link linkend="allow-axfr-ips">netmask instead of only per IP address</link>.
1444	</para>
1445	</listitem>
1446	<listitem>
1447	<para>
1448	Preliminary support for slave operation included. Only for the adventurous right now! See <xref linkend="slave">
1449	</para>
1450	</listitem>
1451	<listitem>
1452	<para>
1453	All record types now documented, see <xref linkend="types">.
1454	</para>
1455	</listitem>
1456	</itemizedlist>
1457	</para>
1458	<sect3><title>Known bugs</title>
1459	<para>
1460	Wildcard CNAMES do not work as they do with bind.
1461	</para>
1462	<para>
1463	Recursion sometimes sends out duplicate packets (fixed in 1.99.9 snapshots)
1464	</para>
1465	<para>
1466	Some stability issues which are caught by the guardian
1467	</para>
1468	</sect3>
1469	<sect3><title>Missing features</title>
1470	<para>
1471	Features present in this document, but disabled or withheld from the current release:
1472	<itemizedlist>
1473	<listitem>
1474	<para>
1475	gmysqlbackend, oraclebackend
1476	</para>
1477	</listitem>
1478	</itemizedlist>
1479
1480	</para>
1481	</sect3>
1482
1483	</sect2>
1484	<sect2 id="changelog-1-99-7"><title>Version 1.99.7 Early Access Prerelease</title>
1485	<para>
1486	Named.conf parsing got a lot of work and many more bind configurations can now be parsed. Furthermore, error reporting was improved.
1487	Stability is looking good.
1488	</para>
1489	<para>
1490	Bugs fixed:
1491	<itemizedlist>
1492	<listitem>
1493	<para>
1494	Bind parser got confused by filenames with underscores and colons.
1495	</para
1496	</listitem>
1497	<listitem>
1498	<para>
1499	Bind parser got confused by spaces in quoted names
1500	</para
1501	</listitem>
1502	<listitem>
1503	<para>
1504	FreeBSD version now stops and starts when instructed to do so.
1505	</para
1506	</listitem>
1507	<listitem>
1508	<para>
1509	Wildcards were off by default, which violates standards. Now on by default.
1510	</para
1511	</listitem>
1512	<listitem>
1513	<para>
1514	--oracle was broken in zone2sql
1515	</para
1516	</listitem>
1517	</itemizedlist>
1518	</para>
1519	<para>
1520	Feature enhancements:
1521	<itemizedlist>
1522	<listitem>
1523	<para>
1524	Line number counting goes on as it should when including files in named.conf
1525	</para>
1526	</listitem>
1527	<listitem>
1528	<para>
1529	Added --no-config to enable users to start the pdns daemon without parsing the configuration file.
1530	</para>
1531	</listitem>
1532	<listitem>
1533	<para>
1534	zone2sql now has --bare for unformatted output which can be used to generate insert statements for different database layouts
1535	</para>
1536	</listitem>
1537	<listitem>
1538	<para>
1539	zone2sql now has --gpgsql, which is an alias for --mysql, to output in a format useful for the default Generic PgSQL backend
1540	</para>
1541	</listitem>
1542	<listitem>
1543	<para>
1544	zone2sql is now documented.
1545	</para>
1546	</listitem>
1547	</itemizedlist>
1548	</para>
1549	<sect3><title>Known bugs</title>
1550	<para>
1551	Wildcard CNAMES do not work as they do with bind.
1552	</para>
1553	</sect3>
1554	<sect3><title>Missing features</title>
1555	<para>
1556	Features present in this document, but disabled or withheld from the current release:
1557	<itemizedlist>
1558	<listitem>
1559	<para>
1560	gmysqlbackend, oraclebackend
1561	</para>
1562	</listitem>
1563	</itemizedlist>
1564
1565	Some of these features will be present in newer releases.
1566	</para>
1567	</sect3>
1568
1569	</sect2>
1570	<sect2><title>Version 1.99.6 Early Access Prerelease</title>
1571	<para>
1572	This version is now running on dns-eu1.powerdns.net and working very well for us. But please remain cautious before
1573	deploying!
1574	</para>
1575	<para>
1576	Bugs fixed:
1577	<itemizedlist>
1578	<listitem>
1579	<para>
1580	Webserver neglected to show log messages
1581	</para
1582	</listitem>
1583	<listitem>
1584	<para>
1585	TCP question/answer miscounted multiple questions over one socket. Fixed misnaming of counter
1586	</para
1587	</listitem>
1588	<listitem>
1589	<para>
1590	Packetcache now detects clock skew and times out entries
1591	</para>
1592	</listitem>
1593	<listitem>
1594	<para>
1595	named.conf parser now reports errors with line number and offending token
1596	</para>
1597	</listitem>
1598	<listitem>
1599	<para>
1600	Filenames in named.conf can now contain :
1601	</para>
1602	</listitem>
1603	</itemizedlist>
1604	</para>
1605	<para>
1606	Feature enhancements:
1607	<itemizedlist>
1608	<listitem>
1609	<para>
1610	The webserver now by default does not print out configuration statements, which might contain database backends. Use
1611	<command>webserver-print-arguments</command> to restore the old behaviour.
1612	</para>
1613	</listitem>
1614	<listitem>
1615	<para>
1616	Generic PostgreSQL backend is now included. Still rather beta.
1617	</para>
1618	</listitem>
1619	</itemizedlist>
1620	</para>
1621	<sect3><title>Known bugs</title>
1622	<para>
1623	FreeBSD version does not stop when requested to do so.
1624	</para>
1625	<para>
1626	Wildcard CNAMES do not work as they do with bind.
1627	</para>
1628	</sect3>
1629	<sect3><title>Missing features</title>
1630	<para>
1631
1632	Features present in this document, but disabled or withheld from the current release:
1633	<itemizedlist>
1634	<listitem>
1635	<para>
1636	gmysqlbackend, oraclebackend
1637	</para>
1638	</listitem>
1639	</itemizedlist>
1640
1641	Some of these features will be present in newer releases.
1642	</para>
1643	</sect3>
1644
1645	</sect2>
1646	<sect2><title>Version 1.99.5 Early Access Prerelease</title>
1647	<para>
1648	The main focus of this release is stability and TCP improvements. This is the first release PowerDNS-the-company actually considers for running
1649	on its production servers!
1650	</para>
1651	<para>
1652	Major bugs fixed:
1653	<itemizedlist>
1654	<listitem>
1655	<para>
1656	Zone2sql received a floating point division by zero error on named.confs with less than 100 domains.
1657	</para
1658	</listitem>
1659	<listitem>
1660	<para>
1661	Huffman encoder failed without specific error on illegal characters in a domain
1662	</para
1663	</listitem>
1664	<listitem>
1665	<para>
1666	Fixed huge memory leaks in TCP code.
1667	</para>
1668	</listitem>
1669	<listitem>
1670	<para>
1671	Removed further file descriptor leaks in guardian respawning code
1672	</para>
1673	</listitem>
1674	<listitem>
1675	<para>
1676	Pipebackend was too chatty.
1677	</para>
1678	</listitem>
1679	<listitem>
1680	<para>
1681	pdns_server neglected to close fds 0, 1 & 2 when daemonizing
1682	</para>
1683	</listitem>
1684	</itemizedlist>
1685	</para>
1686	<para>
1687	Feature enhancements:
1688	<itemizedlist>
1689	<listitem>
1690	<para>
1691	bindbackend can be instructed not to check the ctime of a zone by specifying <command>bind-check-interval=0</command>,
1692	which is also the new default.
1693	</para>
1694	</listitem>
1695	<listitem>
1696	<para>
1697	<command>pdns_server --list-modules</command> lists all available modules.
1698	</para>
1699	</listitem>
1700	</itemizedlist>
1701	</para>
1702	<para>
1703	Performance enhancements:
1704	<itemizedlist>
1705	<listitem>
1706	<para>
1707	TCP code now only creates a new database connection for AXFR.
1708	</para>
1709	</listitem>
1710	<listitem>
1711	<para>
1712	TCP connections timeout rather quickly now, leading to less load on the server.
1713	</para>
1714	</listitem>
1715	</itemizedlist>
1716	</para>
1717	<sect3><title>Known bugs</title>
1718	<para>
1719	FreeBSD version does not stop when requested to do so.
1720	</para>
1721	<para>
1722	Wildcard CNAMES do not work as they do with bind.
1723	</para>
1724	</sect3>
1725	<sect3><title>Missing features</title>
1726	<para>
1727
1728	Features present in this document, but disabled or withheld from the current release:
1729	<itemizedlist>
1730	<listitem>
1731	<para>
1732	gmysqlbackend, oraclebackend, gpgsqlbackend
1733	</para>
1734	</listitem>
1735	</itemizedlist>
1736
1737	Some of these features will be present in newer releases.
1738	</para>
1739	</sect3>
1740
1741	</sect2>
1742	<sect2><title>Version 1.99.4 Early Access Prerelease</title>
1743	<para>
1744	A lot of new named.confs can now be parsed, zone2sql & bindbackend have gained features and stability.
1745	</para>
1746	<para>
1747	Major bugs fixed:
1748	<itemizedlist>
1749	<listitem>
1750	<para>
1751	Label compression was not always enabled, leading to large reply packets sometimes.
1752	</para
1753	</listitem>
1754	<listitem>
1755	<para>
1756	Database errors on TCP server lead to a nameserver reload by the guardian.
1757	</para
1758	</listitem>
1759	<listitem>
1760	<para>
1761	MySQL backend neglected to close its connection properly.
1762	</para>
1763	</listitem>
1764	<listitem>
1765	<para>
1766	BindParser miss parsed some IP addresses and netmasks.
1767	</para>
1768	</listitem>
1769	<listitem>
1770	<para>
1771	Truncated answers were also truncated on the packetcache, leading to truncated TCP answers.
1772	</para>
1773	</listitem>
1774	</itemizedlist>
1775	</para>
1776	<para>
1777	Feature enhancements:
1778	<itemizedlist>
1779	<listitem>
1780	<para>
1781	Zone2sql and the bindbackend now understand the Bind $GENERATE{} syntax.
1782	</para>
1783	</listitem>
1784	<listitem>
1785	<para>
1786	Zone2sql can optionally gloss over non-existing zones with <command>--on-error-resume-next</command>.
1787	</para>
1788	</listitem>
1789	<listitem>
1790	<para>
1791	Zone2sql and the bindbackend now properly expand @ also on the right hand side of records.
1792	</para>
1793	</listitem>
1794	<listitem>
1795	<para>
1796	Zone2sql now sets a default TTL.
1797	</para>
1798	</listitem>
1799	<listitem>
1800	<para>
1801	DNS UPDATEs and NOTIFYs are now logged properly and sent the right responses.
1802	</para>
1803	</listitem>
1804	</itemizedlist>
1805	</para>
1806	<para>
1807	Performance enhancements:
1808	<itemizedlist>
1809	<listitem>
1810	<para>
1811	'Fancy records' are no longer queried for on ANY queries - this is a big speedup.
1812	</para>
1813	</listitem>
1814	</itemizedlist>
1815	</para>
1816	<sect3><title>Known bugs</title>
1817	<para>
1818	FreeBSD version does not stop when requested to do so.
1819	</para>
1820	<para>
1821	Zone2sql refuses named.confs with less than 100 domains.
1822	</para>
1823	<para>
1824	Wildcard CNAMES do not work as they do with bind.
1825	</para>
1826	</sect3>
1827	<sect3><title>Missing features</title>
1828	<para>
1829
1830	Features present in this document, but disabled or withheld from the current release:
1831	<itemizedlist>
1832	<listitem>
1833	<para>
1834	gmysqlbackend, oraclebackend, gpgsqlbackend
1835	</para>
1836	</listitem>
1837	</itemizedlist>
1838
1839	Some of these features will be present in newer releases.
1840	</para>
1841	</sect3>
1842
1843	</sect2>
1844
1845	<sect2><title>Version 1.99.3 Early Access Prerelease</title>
1846	<para>
1847	The big news in this release is the BindBackend which is now capable of parsing many more named.conf Bind configurations.
1848	Furthermore, PDNS has successfully parsed very large named.confs with large numbers of small domains, as well as small numbers of
1849	large domains (TLD).
1850	</para>
1851	<para>
1852	Zone transfers are now also much improved.
1853	</para>
1854	<para>
1855	Major bugs fixed:
1856	<itemizedlist>
1857	<listitem>
1858	<para>
1859	zone2sql leaked file descriptors on each domain, used wrong Bison recursion leading to
1860	parser stack overflows. This limited the amount of domains that could be parsed to 1024.
1861	</para
1862	</listitem>
1863	<listitem>
1864	<para>
1865	zone2sql can now read all known zonefiles, with the exception of those containing $GENERATE
1866	</para
1867	</listitem>
1868	<listitem>
1869	<para>
1870	Guardian relaunching a child lost two file descriptors
1871	</para>
1872	</listitem>
1873	<listitem>
1874	<para>
1875	Don't die on a connection reset by peer during zone transfer.
1876	</para>
1877	</listitem>
1878	<listitem>
1879	<para>
1880	Webserver does not crash anymore on ringbuffer resize
1881	</para>
1882	</listitem>
1883	</itemizedlist>
1884	</para>
1885	<para>
1886	Feature enhancements:
1887	<itemizedlist>
1888	<listitem>
1889	<para>
1890	AXFR can now be disabled, and re-enabled per IP address
1891	</para>
1892	</listitem>
1893	<listitem>
1894	<para>
1895	--help accepts a parameter, will then show only help items with that prefix.
1896	</para>
1897	</listitem>
1898	<listitem>
1899	<para>
1900	zone2sql now accepts a --zone-name parameter
1901	</para>
1902	</listitem>
1903	<listitem>
1904	<para>
1905	BindBackend maturing - 9500 zones parsed in 3.5 seconds. No longer case sensitive.
1906	</para>
1907	</listitem>
1908	</itemizedlist>
1909	</para>
1910	<para>
1911	Performance enhancements:
1912	<itemizedlist>
1913	<listitem>
1914	<para>
1915	Implemented RFC-breaking AXFR format (which is the industry standard). Zone transfers now zoom along
1916	at wirespeed (many megabits/s).
1917	</para>
1918	</listitem>
1919	</itemizedlist>
1920	</para>
1921	<sect3><title>Known bugs</title>
1922	<para>
1923	FreeBSD version does not stop when requested to do so.
1924	</para>
1925	<para>
1926	BindBackend cannot parse zones with $GENERATE statements.
1927	</para>
1928	</sect3>
1929	<sect3><title>Missing features</title>
1930	<para>
1931
1932	Features present in this document, but disabled or withheld from the current release:
1933	<itemizedlist>
1934	<listitem>
1935	<para>
1936	gmysqlbackend, oraclebackend, gpgsqlbackend
1937	</para>
1938	</listitem>
1939	</itemizedlist>
1940
1941	Some of these features will be present in newer releases.
1942	</para>
1943	</sect3>
1944
1945	</sect2>
1946
1947	<sect2><title>Version 1.99.2 Early Access Prerelease</title>
1948	<para>
1949	Major bugs fixed:
1950	<itemizedlist>
1951	<listitem>
1952	<para>
1953	Database backend reload does not hang the daemon anymore
1954	</para>
1955	</listitem>
1956	<listitem>
1957	<para>
1958	Buffer overrun in local socket address initialisation may have caused binding problems
1959	</para>
1960	</listitem>
1961	<listitem>
1962	<para>
1963	setuid changed the uid to the gid of the selected user
1964	</para>
1965	</listitem>
1966	<listitem>
1967	<para>
1968	zone2sql doesn't coredump on invocation anymore. Fixed lots of small issues.
1969	</para>
1970	</listitem>
1971	<listitem>
1972	<para>
1973	Don't parse configuration file when creating configuration file. This was a problem with reinstalling.
1974	</para>
1975	</listitem>
1976	</itemizedlist>
1977	Performance improvements:
1978	<itemizedlist>
1979	<listitem>
1980	<para>
1981	removed a lot of unnecessary gettimeofday calls
1982	</para>
1983	</listitem>
1984	<listitem>
1985	<para>
1986	removed needless select(2) call in case of listening on only one address
1987	</para>
1988	</listitem>
1989	<listitem>
1990	<para>
1991	removed 3 useless syscalls in the fast path
1992	</para>
1993	</listitem>
1994	</itemizedlist>
1995	Having said that, more work may need to be done. Testing on a 486 saw packet rates in a simple setup
1996	(question/wait/answer/question..) improve from 200 queries/second to over 400.
1997	</para>
1998	<para>
1999	Usability improvements:
2000	<itemizedlist>
2001	<listitem>
2002	<para>
2003	Fixed error checking in init.d script (<command>show</command>, <command>mrtg</command>)
2004	</para>
2005	</listitem>
2006	<listitem>
2007	<para>
2008	Added 'uptime' to the mrtg output
2009	</para>
2010	</listitem>
2011	<listitem>
2012	<para>
2013	removed further GNUisms from installer and init.d scripts for use on FreeBSD
2014	</para>
2015	</listitem>
2016	<listitem>
2017	<para>
2018	Debian package and apt repository, thanks to Wichert Akkerman.
2019	</para>
2020	</listitem>
2021	<listitem>
2022	<para>
2023	FreeBSD /usr/ports, thanks to Peter van Dijk (in progress).
2024	</para>
2025	</listitem>
2026	</itemizedlist>
2027
2028
2029	</para>
2030	<para>
2031	Stability may be an issue as well as performance. This version has a tendency to log a bit too much which slows
2032	the nameserver down a lot.
2033	</para>
2034	<sect3><title>Known bugs</title>
2035	<para>
2036	Decreasing a ringbuffer on the website is a sure way to crash the daemon. Zone2sql, while improved, still
2037	has problems with a zone in the following format:
2038
2039	<programlisting>
2040	name IN A 1.2.3.4
2041	IN A 1.2.3.5
2042	</programlisting>
2043
2044	To fix, add 'name' to the second line.
2045	</para>
2046	<para>
2047	Zone2sql does not close filedescriptors.
2048	<para>
2049
2050	<para>
2051	FreeBSD version does not stop when requested via the init.d script.
2052	<para>
2053
2054	</sect3>
2055	<sect3><title>Missing features</title>
2056	<para>
2057	Features present in this document, but disabled or withheld from the current release:
2058	<itemizedlist>
2059	<listitem>
2060	<para>
2061	gmysqlbackend, oraclebackend, gpgsqlbackend
2062	</para>
2063	</listitem>
2064	<listitem>
2065	<para>
2066	fully functioning bindbackend - will try to parse named.conf, but probably fail
2067	</para>
2068	</listitem>
2069	</itemizedlist>
2070
2071	Some of these features will be present in newer releases.
2072
2073
2074	</para>
2075	</sect3>
2076	</sect2>
2077	<sect2><title>Version 1.99.1 Early Access Prerelease</title>
2078	<para>
2079	This is the first public release of what is going to become PDNS 2.0. As such, it is not of production quality.
2080	Even PowerDNS-the-company does not run this yet.
2081	</para>
2082	<para>
2083	Stability may be an issue as well as performance. This version has a tendency to log a bit too much which slows
2084	the nameserver down a lot.
2085	</para>
2086	<sect3><title>Known bugs</title>
2087	<para>
2088	Decreasing a ringbuffer on the website is a sure way to crash the daemon. Zone2sql is very buggy.
2089	</para>
2090	</sect3>
2091	<sect3><title>Missing features</title>
2092	<para>
2093	Features present in this document, but disabled or withheld from the current release:
2094	<itemizedlist>
2095	<listitem>
2096	<para>
2097	gmysqlbackend, oraclebackend, gpgsqlbackend
2098	</para>
2099	</listitem>
2100	<listitem>
2101	<para>
2102	fully functioning bindbackend - will not parse configuration files
2103	</para>
2104	</listitem>
2105	</itemizedlist>
2106
2107	Some of these features will be present in newer releases.
2108
2109
2110	</para>
2111	</sect3>
2112	</sect2>
2113	</sect1>
2114	<sect1 id="thanks-to"><title>Acknowledgements</title>
2115	<para>
2116	PowerDNS is grateful for the help of the following people or institutions:
2117	<itemizedlist>
2118	<listitem><para>Dave Aaldering</para></listitem>
2119	<listitem><para>Wichert Akkerman</para></listitem>
2120	<listitem><para>Antony Antony</para></listitem>
2121	<listitem><para>Mike Benoit (NetNation Communication Inc.)</para></listitem>
2122	<listitem><para>Peter van Dijk</para></listitem>
2123	<listitem><para>Koos van den Hout</para></listitem>
2124	<listitem><para>Andre Koopal</para></listitem>
2125	<listitem><para>Eric Veldhuyzen</para></listitem>
2126	<listitem><para>Paul Wouters</para></listitem>
2127	<listitem><para>Thomas Wouters</para></listitem>
2128	<listitem><para>IETF Namedroppers mailinglist</para></listitem>
2129	</itemizedlist>
2130	Thanks!
2131	</para>
2132	<para>
2133	(these people don't share the blame for any errors or mistakes in powerdns - those are all ours)
2134	</para>
2135	</Chapter>
2136
2137	<Chapter id="installing-on-unix">
2138	<Title>Installing on Unix</Title>
2139
2140	<Para>
2141	After unpacking the PDNS distribution the files need to be moved to
2142	appropriate locations.
2143	</Para>
2144
2145	<Para>
2146	PDNS can be installed in a variety of directories, which can easily be
2147	customised to local policy. Two ways are available - manual and via a menu.
2148	</Para>
2149
2150	<Para>
2151	The menu is invoked by executing the './choosepaths' script and answering the
2152	questions. The manual way involves editing the 'pathconfig' file. The choice
2153	is up to you.
2154	</Para>
2155
2156	<Para>
2157	After deciding paths, change to root and execute the 'installer' script.
2158	This will:
2159	<itemizedlist>
2160	<listitem>
2161	<para>Configure the PowerDNS binary so it knows where the configuration directory is</para>
2162	</listitem>
2163	<listitem>
2164	<para>If necessary, create the configuration directory</para>
2165	</listitem>
2166	<listitem>
2167	<para>Write sample configuration file (not overwriting existing one)</para>
2168	</listitem>
2169	<listitem>
2170	<para>Write a SysV-style init.d script in the configured directory</para>
2171	</listitem>
2172	<listitem>
2173	<para>Move binaries and libraries to the configured places</para>
2174	</listitem>
2175	</itemizedlist>
2176	</Para>
2177
2178	<sect1 id="problems">
2179	<title>Possible problems at this point</title>
2180	<para>
2181	At this point some things may have gone wrong. Typical errors include:
2182	<variablelist>
2183	<varlistentry>
2184	<term><errortype>error while loading shared libraries: libstdc++.so.x: cannot open shared object file: No such file or directory</errortype></term>
2185	<listitem>
2186	<para>
2187	Errors looking like this indicate a mismatch between your PDNS distribution and your Unix operating system. Download the static PDNS
2188	distribution for your operating system and try again. Please contact <email>pdns@powerdns.com</email> if this is impractical.
2189	</para>
2190	</listitem>
2191	</varlistentry>
2192
2193
2194
2195	</variablelist>
2196	</para>
2197	</sect1>
2198
2199	<Sect1 id="testing">
2200	<Title>Testing your install</Title>
2201	<para>
2202	After installing, it is a good idea to test the basic functionality of the software before configuring database backends.
2203	For this purpose, PowerDNS contains the 'bindbackend' which has a domain built in example.com, which is
2204	officially reserved for testing.
2205
2206	To test, edit <filename>pdns.conf</filename> and add the following if not already present:
2207
2208	<screen>
2209	launch=bind
2210	bind-example-zones
2211	</screen>
2212
2213	This configures powerdns to 'launch' the bindbackend, and enable the example zones. To fire up PDNS in testing mode, execute:
2214	<command>/etc/init.d/pdns monitor</command>, where you may have to substitute the location of your SysV init.d location you
2215	specified earlier.
2216
2217	In monitor mode, the pdns process runs in the foreground and is very verbose, which is perfect for testing your install.
2218
2219	If everything went all right, you can query the example.com domain like this:
2220	<screen>
2221	<command>host www.example.com 127.0.0.1</command>
2222	</screen>
2223	www.example.com should now have IP address 1.2.3.4. The <command>host</command> command can usually be found in the dnsutils
2224	package of your operating system. Alternate command is: <command>dig www.example.com A @127.0.0.1</command> or even
2225	<command>nslookup www.example.com 127.0.0.1</command>, although nslookup is not advised for DNS diagnostics.
2226
2227	<itemizedlist>
2228	<listitem>
2229	<para>
2230	example.com SOA record
2231	</para>
2232	</listitem>
2233	<listitem>
2234	<para>
2235	example.com NS record pointing to ns1.example.com
2236	</para>
2237	</listitem>
2238	<listitem>
2239	<para>
2240	example.com NS record pointing to ns2.example.com
2241	</para>
2242	</listitem>
2243	<listitem>
2244	<para>
2245	example.com MX record pointing to mail.example.com
2246	</para>
2247	</listitem>
2248	<listitem>
2249	<para>
2250	example.com MX record pointing to mail1.example.com
2251	</para>
2252	</listitem>
2253	<listitem>
2254	<para>
2255	mail.example.com A record pointing to 4.3.2.1
2256	</para>
2257	</listitem>
2258	<listitem>
2259	<para>
2260	mail1.example.com A record pointing to 5.4.3.2
2261	</para>
2262	</listitem>
2263	<listitem>
2264	<para>
2265	ns1.example.com A record pointing to 4.3.2.1
2266	</para>
2267	</listitem>
2268	<listitem>
2269	<para>
2270	ns2.example.com A record pointing to 5.4.3.2
2271	</para>
2272	</listitem>
2273	<listitem>
2274	<para>
2275	host-0 to host-9999.example.com A record pointing to 2.3.4.5
2276	</para>
2277	</listitem>
2278
2279	</itemizedlist>
2280
2281	When satisfied that basic functionality is there, type <command>QUIT</command> to exit the monitor mode.
2282	The adventurous may also type <command>SHOW *</command> to see some internal statistics.
2283
2284	In case of problems, you will want to read the following section.
2285	</para>
2286
2287	<sect2>
2288	<title>Typical errors</title>
2289	<para>
2290	At this point some things may have gone wrong. Typical errors include:
2291	<variablelist>
2292	<varlistentry>
2293	<term><errortype>binding to UDP socket: Address already in use</errortype></term>
2294	<listitem>
2295	<para>
2296	This means that another nameserver is listening on port 53 already. You can resolve this problem
2297	by determining if it is safe to shutdown the nameserver already present, and doing so. If uncertain,
2298	it is also possible to run PDNS on another port. To do so, add <command>local-port=5300</command> to
2299	<filename>pdns.conf</filename>, and try again. This however implies that you can only test your nameserver
2300	as clients expect the nameserver to live on port 53.
2301	</para>
2302	</listitem>
2303	</varlistentry>
2304	<varlistentry>
2305	<term><errortype>binding to UDP socket: Permission denied</errortype></term>
2306	<listitem>
2307	<para>
2308	You must be superuser in order to be able to bind to port 53. If this is not a possibility,
2309	it is also possible to run PDNS on another port. To do so, add <command>local-port=5300</command> to
2310	<filename>pdns.conf</filename>, and try again. This however implies that you can only test your nameserver
2311	as clients expect the nameserver to live on port 53.
2312	</para>
2313	</listitem>
2314	</varlistentry>
2315	<varlistentry>
2316	<term><errortype>Unable to launch, no backends configured for querying</errortype></term>
2317	<listitem>
2318	<para>
2319	PDNS did not find the <command>launch=bind</command> instruction in pdns.conf.
2320	</para>
2321	</listitem>
2322	</varlistentry>
2323
2324	</variablelist>
2325	</para>
2326	</sect2>
2327	</Sect1>
2328
2329	<sect1 id="pdns-on-unix">
2330	<Title>Running PDNS on unix</Title>
2331
2332	<Para>
2333	PDNS is normally controlled via a SysV-style init.d script, often located in <filename>/etc/init.d</filename> or
2334	<filename>/etc/rc.d/init.d</filename>. This script accepts the following commands:
2335	<variablelist>
2336	<varlistentry>
2337	<term>monitor</term>
2338	<listitem>
2339	<para>
2340	Monitor is a special way to view the daemon. It executes PDNS in the foreground with
2341	a lot of logging turned on, which helps in determining startup problems.
2342
2343	Besides running in the foreground, the raw PDNS control socket is made available. All external
2344	communication with the daemon is normally sent over this socket. While useful, the control console
2345	is not an officially supported feature. Commands which work are: <command>QUIT</command>, <command>SHOW *</command>,
2346	<command>SHOW varname</command>, <command>RPING</command>.
2347	</para>
2348	</listitem>
2349	</varlistentry>
2350	<varlistentry>
2351	<term>start</term>
2352	<listitem>
2353	<para>
2354	Start PDNS in the background. Launches the daemon but makes no special effort to determine success,
2355	as making database connections may take a while. Use <command>status</command> to query success. You
2356	can safely run <command>start</command> many times, it will not start additional PDNS instances.
2357	</para>
2358	</listitem>
2359	</varlistentry>
2360	<varlistentry>
2361	<term>restart</term>
2362	<listitem>
2363	<para>
2364	Restarts PDNS if it was running, starts it otherwise.
2365	</para>
2366	</listitem>
2367	</varlistentry>
2368	<varlistentry>
2369	<term>status</term>
2370	<listitem>
2371	<para>
2372	Query PDNS for status. This can be used to figure out if a launch was successful.
2373	The status found is prefixed by the PID of the main PDNS process.
2374	</para>
2375	</listitem>
2376	</varlistentry>
2377	<varlistentry>
2378	<term>stop</term>
2379	<listitem>
2380	<para>
2381	Requests that PDNS stop. Again, does not confirm success. Success can be ascertained with the <command>status</command> command.
2382	</para>
2383	</listitem>
2384	</varlistentry>
2385
2386	<varlistentry>
2387	<term>dump</term>
2388	<listitem>
2389	<para>
2390	Dumps a lot of statistics of a running PDNS daemon. It is also possible to single out specific variable by using
2391	the <command>show</command> command.
2392	</para>
2393	</listitem>
2394	</varlistentry>
2395
2396	<varlistentry>
2397	<term>show variable</term>
2398	<listitem>
2399	<para>
2400	Show a single statistic, as present in the output of the <command>dump</command>.
2401	</para>
2402	</listitem>
2403	</varlistentry>
2404
2405	<varlistentry>
2406	<term>mrtg</term>
2407	<listitem>
2408	<para>
2409	See the performance monitoring <xref linkend="monitoring">.
2410	</para>
2411	</listitem>
2412	</varlistentry>
2413
2414	</variablelist>
2415	</Para>
2416
2417	</sect1>
2418	</Chapter>
2419
2420	<Chapter id="windows">
2421	<Title>Installing on Microsoft Windows</Title>
2422	<para>
2423	<note>
2424	<para>
2425	PowerDNS support for Windows is, as of 1.99.12, very recent and therefore quite 'beta'. For reliability, we currently advise the use of
2426	the Unix versions. Furthermore there is no support for master or slave operation in the ODBC backend, which is the only one provided currently.
2427	This will be fixed soon.
2428	</para>
2429	</note>
2430	</para>
2431	<para>
2432	As of 1.99.12, PowerDNS supports Windows natively. PDNS can act as an NT service and works with any ODBC drivers you may have.
2433	</para>
2434	<para>
2435	To install PowerDNS for Windows you should check if your PC meets the following requirements:
2436	<itemizedlist>
2437	<listitem>
2438	<para>
2439	A PC running Microsoft NT (with a recent servicepack and at least mdac 2.5), 2000 or XP.
2440	</para>
2441	</listitem>
2442	<listitem>
2443	<para>An ODBC source containing valid zone information (an example MS Access database is supplied in the form of <filename>powerdns.mdb</filename>).
2444	</para>
2445	</listitem>
2446	</itemizedlist>
2447	</para>
2448
2449	<para>
2450	If your system meets these requirements, download the installer from <ulink url="http://www.powerdns.com/pdns/">http://www.powerdns.com/pdns/</ulink>.
2451	After downloading the file begin the installation procedure by starting <filename>powerdns-VERSION.exe</filename>.
2452
2453	</para>
2454
2455	<para>
2456	After installing the software you should create a valid ODBC source.
2457	To do this you have open the ODBC sources dialog: <filename>Start->Settings->Control Panel->Administrative Tools->Data Sources (ODBC)</filename>.
2458	</para>
2459
2460	<para>
2461	We'll use the example zone database that is included in the installation to explain how to create a source.
2462	</para>
2463
2464	<para>
2465	When you are in the ODBC sources dialog you activate the <filename>System DSN</filename> tab.
2466	<note><para>It is important to create a System DSN instead of an User DNS, otherwise the ODBC backend cannot function.</para></note>
2467	</para>
2468
2469	<para>
2470	Press <filename>Add...</filename>, then you have to select a driver.
2471	</para>
2472
2473	<para>
2474	Select <filename>Microsoft Access Driver (*.mdb)</filename>.
2475	</para>
2476
2477	<para>
2478	Use <filename>PowerDNS</filename> as the DSN name, you can leave the description empty.
2479	</para>
2480
2481	<para>
2482	Then press <filename>Select...</filename> to select the database (ie. <filename>C:\Program Files\PowerDNS\powerdns.mdb</filename>).
2483	</para>
2484
2485	<para>
2486	Press <function>Ok</function> and you should be done.
2487	</para>
2488
2489	<para>
2490	For more information, see <xref linkend="odbc">.
2491	</para>
2492
2493	<sect1 id="windows-configuration">
2494	<title>Configuring PDNS on Microsoft Windows</title>
2495
2496	<para>
2497	You can specify program parameters in the <filename>pdns.conf</filename> file
2498	which should be located in pdns directory (ie. <filename>C:\Program Files\PowerDNS\</filename>).
2499	</para>
2500
2501	<para>
2502	To see a list of available parameters you can run <filename>pdns.exe --help</filename>.
2503	</para>
2504
2505	<note>
2506	<para>
2507	A default configuration file has been supplied with the installation.
2508	</para>
2509	</note>
2510
2511	</sect1>
2512
2513	<sect1 id="running-on-windows">
2514	<title>Running PDNS on Microsoft Windows</title>
2515
2516	<para>
2517	If you installed pdns on Windows NT, 2000 or XP you can run pdns as a service.
2518	</para>
2519
2520	<para>
2521	This is how to do it:
2522	Go to services (<filename>Start->Settings->Control Panel->Administrative Tools->Services</filename>) and locate <filename>PDNS</filename> (you should have registered the program as a NT service during the installation).
2523	</para>
2524
2525	<para>
2526	Double-click on <filename>PDNS</filename> and push the start button. You should now see a progress bar that gets to the end and see the status change to 'Started'.
2527	</para>
2528
2529	<para>
2530	This is the same as starting pdns like this:
2531	<filename>pdns.exe --ntservice</filename>
2532	</para>
2533
2534	<para>
2535	If you haven't registered pdns as a service during the installation you can do so from the commandline by starting pdns like this:
2536	<filename>pdns.exe --register-service</filename>
2537	</para>
2538
2539	<para>
2540	You can run pdns as a standard console program by using a command prompt or <filename>Start->Run...</filename>
2541	This way you can specify command-line parameters (see the documentation for commandline options).
2542	</para>
2543
2544	<para>
2545	If you chose to add a PowerDNS menu to the start menu during the installation you can start pdns using the pdns shortcut in that menu.
2546	</para>
2547
2548	</sect1>
2549	</Chapter>
2550
2551	<Chapter id="configuring-db-connection">
2552	<title>Configure database connectivity</title>
2553	<para>
2554	The default PDNS distribution comes with a simple MySQL backend built in, which we will now use for
2555	demonstrating database connectivity. This backend is called 'mysql', and needs to be configured
2556	in <filename>pdns.conf</filename>. Add the following lines, adjusted for your local setup:
2557
2558	<screen>
2559	launch=mysql
2560	mysql-host=127.0.0.1
2561	mysql-user=root
2562	mysql-dbname=pdnstest
2563	</screen>
2564
2565	Remove any earlier <command>launch</command> statements. Also remove the <command>bind-example-zones</command>
2566	statement as the <command>bind</command> module is no longer launched.
2567	</para>
2568	<para>
2569	WARNING! Make sure that you can actually resolve the hostname of your database without accessing the database! It is advised to supply
2570	an IP address here to prevent chicken/egg problems!
2571	</para>
2572	<para>
2573	Now start PDNS using the monitor command:
2574	<screen>
2575	# /etc/init.d/pdns monitor
2576	(...)
2577	15:31:30 PowerDNS 1.99.0 (Mar 12 2002, 15:00:28) starting up
2578	15:31:30 About to create 3 backend threads
2579	15:31:30 [MySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
2580	15:31:30 [MySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
2581	15:31:30 [MySQLbackend] Failed to connect to database: Error: Unknown database 'pdnstest'
2582	</screen>
2583
2584	This is as to be expected - we did not yet add anything to MySQL for PDNS to read from. At this point you may also see
2585	other errors which indicate that PDNS either could not find your MySQL server or was unable to connect to it. Fix these
2586	before proceeding.
2587	</para>
2588	<para>
2589	General MySQL knowledge is assumed in this chapter, please do not interpret these commands as DBA advice!
2590	</para>
2591	<sect1 id="configuring-mysql"><title>Configuring MySQL</title>
2592	<para>
2593	Connect to MySQL as a user with sufficient privileges and issue the following commands:
2594	<screen>
2595	# mysql
2596	mysql> CREATE DATABASE pdnstest;
2597	mysql> use pdnstest;
2598
2599	mysql> CREATE TABLE records (
2600	id int(11) NOT NULL auto_increment,
2601	domain_id int(11) default NULL,
2602	name varchar(255) default NULL,
2603	type varchar(6) default NULL,
2604	content varchar(255) default NULL,
2605	ttl int(11) default NULL,
2606	prio int(11) default NULL,
2607	change_date int(11) default NULL,
2608	PRIMARY KEY (id),
2609	KEY name_index(name),
2610	KEY nametype_index(name,type),
2611	KEY domainid_index(domain_id)
2612	);
2613	</screen>
2614
2615	Now we have a database and an empty table. PDNS should now be able to launch in monitor mode and display no errors:
2616
2617	<screen>
2618	# /etc/init.d/pdns monitor
2619	(...)
2620	15:31:30 PowerDNS 1.99.0 (Mar 12 2002, 15:00:28) starting up
2621	15:31:30 About to create 3 backend threads
2622	15:39:55 [MySQLbackend] MySQL connection succeeded
2623	15:39:55 [MySQLbackend] MySQL connection succeeded
2624	15:39:55 [MySQLbackend] MySQL connection succeeded
2625	</screen>
2626
2627	A sample query sent to the database should now return quickly without data:
2628	<screen>
2629	$ host www.test.com 127.0.0.1
2630	www.test.com A record currently not present at localhost
2631	</screen>
2632
2633	And indeed, the control console now shows:
2634	<screen>
2635	Mar 12 15:41:12 We're not authoritative for 'www.test.com', sending unauth normal response
2636	</screen>
2637
2638	Now we need to add some records to our database:
2639	<screen>
2640	# mysql pdnstest
2641	mysql>
2642	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2643	VALUES (1,'test.com','localhost ahu@ds9a.nl 1','SOA',86400,NULL);
2644	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2645	VALUES (1,'test.com','dns-us1.powerdns.net','NS',86400,NULL);
2646	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2647	VALUES (1,'test.com','dns-eu1.powerdns.net','NS',86400,NULL);
2648	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2649	VALUES (1,'www.test.com','199.198.197.196','A',120,NULL);
2650	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2651	VALUES (1,'mail.test.com','195.194.193.192','A',120,NULL);
2652	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2653	VALUES (1,'localhost.test.com','127.0.0.1','A',120,NULL);
2654	INSERT INTO records (domain_id, name, content, type,ttl,prio)
2655	VALUES (1,'test.com','mail.test.com','MX',120,25);
2656	</screen>
2657
2658	If we now requery our database, <command>www.test.com</command> should be present:
2659	<screen>
2660	$ host www.test.com 127.0.0.1
2661	www.test.com A 199.198.197.196
2662
2663	$ host -v -t mx test.com 127.0.0.1
2664	Address: 127.0.0.1
2665	Aliases: localhost
2666
2667	Query about test.com for record types MX
2668	Trying test.com ...
2669	Query done, 1 answer, authoritative status: no error
2670	test.com 120 IN MX 25 mail.test.com
2671	Additional information:
2672	mail.test.com 120 IN A 195.194.193.192
2673	</screen>
2674
2675	To confirm what happened, issue the command <command>SHOW *</command> to the control console:
2676	<screen>
2677	% show *
2678	corrupt-packets=0,latency=0,packetcache-hit=2,packetcache-miss=5,packetcache-size=0,
2679	qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,tcp-queries=0,
2680	timedout-packets=0,udp-answers=7,udp-queries=7,
2681	%
2682	</screen>
2683	The actual numbers will vary somewhat. Now enter <command>QUIT</command> and start PDNS as a regular daemon, and check launch status:
2684
2685	<screen>
2686	# /etc/init.d/pdns start
2687	pdns: started
2688	# /etc/init.d/pdns status
2689	pdns: 8239: Child running
2690	# /etc/init.d/pdns dump
2691	pdns: corrupt-packets=0,latency=0,packetcache-hit=0,packetcache-miss=0,
2692	packetcache-size=0,qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,
2693	tcp-queries=0,timedout-packets=0,udp-answers=0,udp-queries=0,
2694	</screen>
2695
2696	You now have a working database driven nameserver! To convert other zones already present, use the <command>zone2sql</command>
2697	described in Appendix A.
2698	</para>
2699	<sect2><title>Common problems</title>
2700	<para>
2701	Most problems involve PDNS not being able to connect to the database.
2702	<variablelist>
2703	<varlistentry>
2704	<term><errortype> Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)</errortype></term>
2705	<listitem>
2706	<para>
2707	Your MySQL installation is probably defaulting to another location for its socket. Can be resolved
2708	by figuring out this location (often <filename>/var/run/mysqld.sock</filename>), and specifying it
2709	in the configuration file with the <command>mysql-socket</command> parameter.
2710	</para>
2711	<para>
2712	Another solution is to not connect to the socket, but to 127.0.0.1, which can be achieved by specifying
2713	<command>mysql-host=127.0.0.1</command>.
2714	</para>
2715	</listitem>
2716	</varlistentry>
2717	<varlistentry>
2718	<term><errortype>Host 'x.y.z.w' is not allowed to connect to this MySQL server</errortype></term>
2719	<listitem>
2720	<para>
2721	These errors are generic MySQL errors. Solve them by trying to connect to your MySQL database with the MySQL
2722	console utility <command>mysql</command> with the parameters specified to PDNS. Consult the MySQL documentation.
2723	</para>
2724	</listitem>
2725	</varlistentry>
2726	</variablelist>
2727	</sect2>
2728	</sect1>
2729	</chapter>
2730
2731	<Chapter id="pipebackend-dynamic-resolution">
2732	<title>Dynamic resolution using the PipeBackend</title>
2733	<para>
2734	Also included in the PDNS distribution is the PipeBackend. The PipeBackend is primarily meant for
2735	allowing rapid development of new backends without tight integration with PowerDNS. It allows
2736	end-users to write PDNS backends in any language. A perl sample is provided.
2737
2738	The PipeBackend is also very well suited for dynamic resolution of queries. Example applications include
2739	DNS based loadbalancing, geo-direction, DNS based failover with low TTLs.
2740	</para>
2741	<sect1 id="pipe-and-bind"><title>Deploying the PipeBackend with the BindBackend</title>
2742	<para>
2743	Included with the PDNS distribution is the example.pl backend which has knowledge of the example.com zone, just like
2744	the BindBackend. To install both, add the following to your <filename>pdns.conf</filename>:
2745	<screen>
2746	launch=pipe,bind
2747	bind-example-zones
2748	pipe-command=location/of/backend.pl
2749	</screen>
2750	Please adjust the <command>pipe-command</command> statement to the location of the unpacked PDNS distribution. If your backend is slow,
2751	raise <command>pipe-timeout</command> from its default of 2000ms.
2752
2753	Now launch PDNS in monitor mode, and perform some queries. Note the difference with the earlier experiment where only the
2754	BindBackend was loaded. The PipeBackend is launched first and thus gets queried first.
2755
2756	The sample backend.pl script knows about:
2757	<itemizedlist>
2758	<listitem>
2759	<para>
2760	webserver.example.com A records pointing to 1.2.3.4, 1.2.3.5, 1.2.3.6
2761	</para>
2762	</listitem>
2763	<listitem>
2764	<para>
2765	www.example.com CNAME pointing to webserver.example.com
2766	</para>
2767	</listitem>
2768	<listitem>
2769	<para>
2770	MBOXFW (mailbox forward) records pointing to powerdns@example.com.
2771	See the smtpredir documentation for information about MBOXFW.
2772	</para>
2773	</listitem>
2774	</itemizedlist>
2775
2776	For more information about how to write exciting backends with the PipeBackend, see Appendix A.
2777	</para>
2778	</sect1>
2779	</chapter>
2780
2781	<Chapter id="monitoring">
2782	<title>Logging & Monitoring PDNS performance</title>
2783	<para>
2784	In a production environment, you will want to be able to monitor PDNS performance. For this purpose, currently
2785	two methods are available, the webserver and the init.d
2786	<command>dump</command>, <command>show</command> and
2787	<command>mrtg</command>, commands. Furthermore, PDNS can perform a configurable amount of operational logging. This chapter
2788	also explains how to configure syslog for best results.
2789	</para>
2790	<sect1 id="webserver"><title>Webserver</title>
2791	<para>
2792	To launch the internal webserver, add a <command>webserver</command> statement to the pdns.conf. This
2793	will instruct the PDNS daemon to start a webserver on localhost at port 8081, without password protection.
2794	Only local users (on the same host) will be able to access the webserver by default.
2795
2796	The webserver lists a lot of information about the PDNS process, including frequent queries, frequently failing queries,
2797	lists of remote hosts sending queries, hosts sending corrupt queries etc. The webserver does not allow
2798	remote management of the daemon.
2799
2800	The following nameserver related configuration items are available:
2801	<variablelist>
2802	<varlistentry>
2803	<term>webserver</term>
2804	<listitem>
2805	<para>
2806	If set to anything but 'no', a webserver is launched.
2807	</para>
2808	</listitem>
2809	</varlistentry>
2810	<varlistentry>
2811	<term>webserver-address</term>
2812	<listitem>
2813	<para>
2814	Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer
2815	is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the
2816	physical IP address of your nameserver.
2817	</para>
2818	</listitem>
2819	</varlistentry>
2820	<varlistentry>
2821	<term>webserver-password</term>
2822	<listitem>
2823	<para>
2824	If set, viewers will have to enter this plaintext password in order to gain access to the statistics.
2825	</para>
2826	</listitem>
2827	</varlistentry>
2828	<varlistentry>
2829	<term>webserver-port</term>
2830	<listitem>
2831	<para>
2832	Port to bind the webserver to. Defaults to 8081.
2833	</para>
2834	</listitem>
2835	</varlistentry>
2836
2837	</variablelist>
2838	</para>
2839	</sect1>
2840	<sect1 id="init-d-commands"><title>Via init.d commands</title>
2841	<para>
2842	As mentioned before, the init.d commands <command>dump</command>, <command>show</command> and
2843	<command>mrtg</command> fetch data from a running PDNS process. Especially <command>mrtg</command> is powerful -
2844	it outputs data in a format that is ready for processing by the MRTG graphing tool.
2845	</para>
2846	<para>
2847	MRTG can make insightful graphics on the performance of your nameserver, enabling the operator to easily spot trends.
2848	MRTG can be found on
2849	<ulink url="http://people.ee.ethz.ch/~oetiker/webtools/mrtg/mrtg.html">
2850	http://people.ee.ethz.ch/~oetiker/webtools/mrtg/mrtg.html
2851	</ulink>
2852	</para>
2853	<para>
2854	A sample mrtg.conf:
2855	<screen>
2856	Interval: 5
2857	WorkDir: /var/www/mrtg
2858	WriteExpires: yes
2859	Options[_]: growright,nopercent
2860	XSize[_]: 600
2861
2862	#---------------------------------------------------------------
2863
2864	Target[udp-queries]: `/etc/init.d/pdns mrtg udp-queries udp-answers`
2865	Options[udp-queries]: growright,nopercent,perminute
2866	MaxBytes[udp-queries]: 600000
2867	AbsMax[udp-queries]: 600000
2868	Title[udp-queries]: Queries per minute
2869	PageTop[udp-queries]: <H2>Queries per minute</H2>
2870	WithPeak[udp-queries]: ymwd
2871	YLegend[udp-queries]: queries/minute
2872	ShortLegend[udp-queries]: q/m
2873	LegendI[udp-queries]: udp-questions
2874	LegendO[udp-queries]: udp-answers
2875
2876
2877	Target[perc-failed]: `/etc/init.d/pdns mrtg udp-queries udp-answers`
2878	Options[perc-failed]: growright,dorelpercent,perminute
2879	MaxBytes[perc-failed]: 600000
2880	AbsMax[perc-failed]: 600000
2881	Title[perc-failed]: Queries per minute, with percentage success
2882	PageTop[perc-failed]: <H2>Queries per minute, with percentage success</H2>
2883	WithPeak[perc-failed]: ymwd
2884	YLegend[perc-failed]: queries/minute
2885	ShortLegend[perc-failed]: q/m
2886	LegendI[perc-failed]: udp-questions
2887	LegendO[perc-failed]: udp-answers
2888
2889
2890	Target[packetcache-rate]: `/etc/init.d/pdns mrtg packetcache-hit udp-queries`
2891	Options[packetcache-rate]: growright,dorelpercent,perminute
2892	Title[packetcache-rate]: packetcache hitrate
2893	MaxBytes[packetcache-rate]: 600000
2894	AbsMax[packetcache-rate]: 600000
2895	PageTop[packetcache-rate]: <H2>packetcache hitrate</H2>
2896	WithPeak[packetcache-rate]: ymwd
2897	YLegend[packetcache-rate]: queries/minute
2898	ShortLegend[packetcache-rate]: q/m
2899	LegendO[packetcache-rate]: total
2900	LegendI[packetcache-rate]: hit
2901
2902	Target[packetcache-missrate]: `/etc/init.d/pdns mrtg packetcache-miss udp-queries`
2903	Options[packetcache-missrate]: growright,dorelpercent,perminute
2904	Title[packetcache-missrate]: packetcache MISSrate
2905	MaxBytes[packetcache-missrate]: 600000
2906	AbsMax[packetcache-missrate]: 600000
2907	PageTop[packetcache-missrate]: <H2>packetcache MISSrate</H2>
2908	WithPeak[packetcache-missrate]: ymwd
2909	YLegend[packetcache-missrate]: queries/minute
2910	ShortLegend[packetcache-missrate]: q/m
2911	LegendO[packetcache-missrate]: total
2912	LegendI[packetcache-missrate]: MISS
2913
2914	Target[latency]: `/etc/init.d/pdns mrtg latency`
2915	Options[latency]: growright,nopercent,gauge
2916	MaxBytes[latency]: 600000
2917	AbsMax[latency]: 600000
2918	Title[latency]: Query/answer latency
2919	PageTop[latency]: <H2>Query/answer latency</H2>
2920	WithPeak[latency]: ymwd
2921	YLegend[latency]: usec
2922	ShortLegend[latency]: usec
2923	LegendO[latency]: latency
2924	LegendI[latency]: latency
2925
2926	Target[recursing]: `/etc/init.d/pdns mrtg recursing-questions recursing-answers`
2927	Options[recursing]: growright,nopercent,gauge
2928	MaxBytes[recursing]: 600000
2929	AbsMax[recursing]: 600000
2930	Title[recursing]: Recursive questions/answers
2931	PageTop[recursing]: <H2>Recursing questions/answers</H2>
2932	WithPeak[recursing]: ymwd
2933	YLegend[recursing]: queries/minute
2934	ShortLegend[recursing]: q/m
2935	LegendO[recursing]: recursing-questions
2936	LegendI[recursing]: recursing-answers
2937
2938	</screen>
2939	</para>
2940	<sect1 id="syslog"><title>Operational logging using syslog</title>
2941	<para>(<command>logging-facility</command> is available from 1.99.10 and onwards)</para>
2942	<para>
2943	This chapter assumes familiarity with syslog, the unix logging device. PDNS logs messages with different levels. The more urgent the
2944	message, the lower the 'priority'. By default, PDNS will only log messages with an urgency of 3 or lower, but this can be changed
2945	using the <command>loglevel</command> setting in the configuration file. Setting it to 0 will eliminate all logging, 9 will log
2946	everything.
2947	</para>
2948	<para>
2949	By default, logging is performed under the 'DAEMON' facility which is shared with lots of other programs. If you regard nameserving
2950	as important, you may want to have it under a dedicated facility so PDNS can log to its own files, and not clutter generic files.
2951	</para>
2952	<para>
2953	For this purpose, syslog knows about 'local' facilities, numbered from LOCAL0 to LOCAL7. To move PDNS logging to LOCAL0, add
2954	<command>logging-facility=0</command> to your configuration.
2955	</para>
2956	<para>
2957	Furthermore, you may want to have separate files for the differing prioties - preventing lower priority messages from obscuring
2958	important ones.
2959	</para>
2960	<para>
2961	A sample syslog.conf might be:
2962	<programlisting>
2963	local0.info -/var/log/pdns.info
2964	local0.warn -/var/log/pdns.warn
2965	local0.err /var/log/pdns.err
2966	</programlisting>
2967	</para>
2968	<para>
2969	Where local0.err would store the really important messages. For performance and diskspace reasons, it is advised
2970	to audit your syslog.conf for statements also logging PDNS activities. Many syslog.confs have a '.' statement to
2971	/var/log/syslog, which you may want to remove.
2972	</para>
2973	<para>
2974	For performance reasons, be especially certain that no large amounts of synchronous logging take place. Under Linux, this
2975	is indicated by filenames not starting with a '-' - indicating a synchronous log, which hurts performance.
2976	</para>
2977	</sect1>
2978	</chapter>
2979	<chapter id="security"><title>Security settings & considerations</title>
2980	<sect1 id="settings"><title>Settings</title>
2981	<para>PDNS has several options to easily allow it to run more securely. Most notable are the <command>chroot</command>,
2982	<command>setuid</command> and <command>setgid</command> options which can be specified.</para>
2983
2984	<sect2><title>Running as a less privileged identity</title>
2985	<para>
2986	By specifying <command>setuid</command> and <command>setgid</command>, PDNS changes to this identity shortly after
2987	binding to the privileged DNS ports. These options are highly recommended. It is suggested that a separate identity
2988	is created for PDNS as the user 'nobody' is in fact quite powerful on most systems.
2989	</para>
2990
2991	<para>
2992	Both these parameters can be specified either numerically or as real names.
2993	You should set these parameters immediately if they are not set!
2994	</para>
2995	<sect2><title>Jailing the process in a chroot</title>
2996	<para>
2997	The <command>chroot</command> option secures PDNS to its own directory so that even if it should become compromised and
2998	under control of external influences, it will have a hard time affecting the rest of the system.
2999	</para>
3000	<para>
3001	Even though this will hamper hackers a lot, chroot jails have been known to be broken.
3002	</para>
3003	<para>
3004	When chrooting PDNS, take care that backends will be able to get to their files. Many databases need access to a UNIX
3005	domain socket which should live within the chroot. It is often possible to hardlink such a socket into the chroot dir.
3006	</para><para>
3007	The default PDNS configuration is best chrooted to <filename>./</filename>, which boils down to the configured location
3008	of the controlsocket.
3009	</para><para>
3010	This is achieved by adding the following to pdns.conf: <command>chroot=./</command>, and restarting PDNS.
3011	</para>
3012	</sect2>
3013	</sect1>
3014	<sect1 id="considerations"><title>Considerations</title>
3015	<para>
3016	In general, make sure that the PDNS process is unable to execute commands on your backend database.
3017	Most database backends will only need SELECT privilege. Take care to not connect to your database as the 'root'
3018	or 'sa' user, and configure the chosen user to have very slight privileges.
3019	</para>
3020	<para>
3021	Databases empathic-ally do not need to run on the same machine that runs PDNS! In fact, in benchmarks
3022	it has been discovered that having a separate database machine actually improves performance.
3023	</para>
3024	<para>
3025	Separation will enhance your database security highly. Recommended.
3026	</para>
3027	</sect1>
3028	</chapter>
3029
3030	<chapter id="virtual"><title>Virtual hosting</title>
3031	<para>
3032	It may be advantageous to run multiple separate PDNS installations on a single host, for example to make sure
3033	that different customers cannot affect each others zones. PDNS fully supports running multiple instances on one host.
3034	</para>
3035	<para>
3036	To generate additional PDNS instances, copy the init.d script <filename>pdns</filename> to <filename>pdns-name</filename>,
3037	where <filename>name</filename> is the name of your virtual configuration. Must not contain a - as this will confuse the
3038	script.
3039	</para>
3040	<para>
3041	When you launch PDNS via this renamed script, it will seek configuration instructions not in <filename>pdns.conf</filename>
3042	but in <filename>pdns-name.conf</filename>, allowing for separate specification of parameters.
3043	</para>
3044	<para>
3045	Be aware however that the init.d <command>force-stop</command> will kill all PDNS instances!
3046	</para>
3047	</chapter>
3048
3049	<chapter id="performance"><title>Performance related settings</title>
3050	<para>
3051	Different backends will have different characteristics - some will want to have more parallel
3052	instances than others. In general, if your backend is latency bound, like most relational databases are,
3053	it pays to open more backends.
3054	</para>
3055	<para>
3056	This is done with the <command>distributor-threads</command> setting. Of special importance is the choice between 1
3057	or more backends. In case of only 1 thread, PDNS reverts to unthreaded operation which may be a lot faster, depending
3058	on your operating system and architecture.
3059	</para>
3060	<para>
3061	Another very important setting <command>cache-ttl</command>. PDNS caches entire packets it sends out so as to save the
3062	time to query backends to assemble all data. The default setting of 10 seconds may be low for high traffic sites, a value of
3063	60 seconds rarely leads to problems.
3064	</para>
3065	<para>
3066	Some PDNS operators set cache-ttl to many hours or even days, and use <command>pdns_control purge</command> to selectively
3067	or globally notify PDNS of changes made in the backend. Also look at the Query Cache described in this chapter. It may
3068	materially improve your performance.
3069	</para>
3070	<para>
3071	To determine if PDNS is unable to keep up with packets, determine the value of the <command>qsize-q</command> variable.
3072	This represents the number of packets waiting for database attention. During normal operations the queue should be small.
3073	</para>
3074	<para>
3075	If it is known that backends will not contain CNAME records, the <command>skip-cname</command> setting can be used to prevent
3076	the normally mandatory CNAME lookup that is needed at least once for each DNS query.
3077	</para>
3078
3079	<para>
3080	Much the same holds for the <command>wildcards</command> setting. On by default, each non-existent query will lead to a number of additional
3081	wildcard queries. If it is known that the backends do not contain wildcard records, performance can be improved by adding <command>wildcards=no</command>
3082	to <filename>pdns.conf</filename>.
3083	</para>
3084	<para>
3085	Logging truly kills performance as answering a question from the cache is an order of magnitude less work than logging a
3086	line about it. Busy sites will prefer to turn <command>log-dns-details</command> and <command>log-failed-updates</command>
3087	off.
3088	</para>
3089	<sect1 id="packetcache"><title>Packet Cache</title>
3090	<para>
3091	PDNS by default uses the 'Packet Cache' to recognise identical questions and supply them with identical answers, without any further
3092	processing. The default time to live is 10 seconds. It has been observed that the utility of the packet cache increases with the load on
3093	your nameserver.
3094	</para>
3095	<para>
3096	Not all backends may benefit from the packetcache. If your backend is memory based and does not lead to context switches, the packetcache
3097	may actually hurt performance.
3098	</para>
3099	<para>
3100	The size of the packetcache can be observed with <command>/etc/init.d/pdns show packetcache-size</command>
3101	</para>
3102	</sect1>
3103	<sect1 id="querycache"><title>Query Cache</title>
3104	<para>
3105	Besides entire packets, PDNS can also cache individual backend queries. Each DNS query leads to a number of backend queries,
3106	the most obvious additional backend query is the check for a possible CNAME. So, when a query comes in for the 'A' record for
3107	'www.powerdns.com', PDNS must first check for a CNAME for 'www.powerdns.com'.
3108	</para>
3109	<para>
3110	The Query Cache caches these backend queries, many of which are quite repetitive. PDNS only caches queries with no answer,
3111	or with exactly one. In the future this may be expanded but this lightweight solution is very simple and therefore fast.
3112	</para>
3113	<para>
3114	Most gain is made from caching negative entries, ie, queries that have no answer. As these take little memory to store and
3115	are typically not a real problem in terms of speed-of-propagation, the default TTL for negative queries is a rather high 60 seconds.
3116	</para>
3117	<para>
3118	This only is a problem when first doing a query for a record, adding it, and immediately doing a query for that record again. It may
3119	then take up to 60 seconds to appear. Changes to existing records however do not fall under the negative query ttl (
3120	<command>negquery-cache-ttl</command>), but under the generic <command>query-ttl</command> which defaults to 20 seconds.
3121	</para>
3122	<para>
3123	The default values should work fine for many sites. When tuning, keep in mind that the Query Cache mostly saves database access
3124	but that the Packet Cache also saves a lot of CPU because 0 internal processing is done when answering a question from the
3125	Packet Cache.
3126	</para>
3127	</sect1>
3128	</chapter>
3129	<chapter id="migration"><title>Migrating to PDNS</title>
3130	<para>
3131	Before migrating to PDNS a few things should be considered.
3132	<variablelist>
3133	<varlistentry>
3134	<term>PDNS is not a recursing nameserver on its own</term>
3135	<listitem>
3136	<para>
3137	If PDNS receives a question for which it is not authoritative, it can't go out on the net to figure out an answer. However,
3138	because many installations are expected to be both authoritative and recursing, PDNS can use a separate recursing backend
3139	to provide non-authoritative answers. See <xref linkend="recursion"> for more details.
3140	</para>
3141	</listitem></varlistentry>
3142	<varlistentry>
3143	<term>PDNS does not operate as a 'slave' server with all backends</term>
3144	<listitem>
3145	<para>
3146	Only the PostgreSQL backend has, of version 1.99.9, the ability to act as a slave.
3147	</para>
3148	</listitem>
3149	</varlistentry>
3150	</variablelist>
3151	To migrate, the <command>zone2sql</command> tool is provided.
3152	</para>
3153	<sect1 id="zone2sql"><title>Zone2sql</title>
3154	<para>
3155	Zone2sql parses Bind named.conf files and zonefiles and outputs SQL
3156	on standard out, which can then be fed to your database.
3157	</para>
3158	<para>
3159	Zone2sql understands the Bind master file extension '$GENERATE' and will also honour '$ORIGIN' and '$TTL'.
3160	</para>
3161	<para>
3162	For backends supporting slave operation (currently only the PostgreSQL backend), there is also an option to keep slave zones as slaves,
3163	and not convert them to native operation.
3164	</para>
3165	<para>
3166	By default, zone2sql outputs code suitable for the mysqlbackend, but it can also generate SQL for the Generic PostgreSQL and Oracle backends.
3167	The following commands are available:
3168	</para>
3169
3170	<para>
3171	<variablelist>
3172	<varlistentry>
3173	<term>--bare</term>
3174	<listitem>
3175	<para>
3176	Output in a bare format, suitable for further parsing. The output is formatted as follows:
3177	<screen>
3178	domain_id<TAB>'qname'<TAB>'qtype'<TAB>'content'<TAB>prio<TAB>ttl
3179	</screen>
3180	</para>
3181	</listitem>
3182	</varlistentry>
3183	<varlistentry>
3184	<term>--gmysql</term>
3185	<listitem>
3186	<para>
3187	Output in format suitable for the default configuration of the Generic MySQL backend.
3188	</para>
3189	</listitem>
3190	</varlistentry>
3191	<varlistentry>
3192	<term>--gpgsql</term>
3193	<listitem>
3194	<para>
3195	Output in format suitable for the default configuration of the Generic PostgreSQL backend.
3196	</para>
3197	</listitem>
3198	</varlistentry>
3199	<varlistentry>
3200	<term>--help</term>
3201	<listitem>
3202	<para>
3203	List options.
3204	</para>
3205	</listitem>
3206	</varlistentry>
3207	<varlistentry>
3208	<term>--mysql</term>
3209	<listitem>
3210	<para>
3211	Output in format suitable for the default configuration of the MySQL backend. Default.
3212	</para>
3213	</listitem>
3214	</varlistentry>
3215	<varlistentry>
3216	<term>--named-conf=...</term>
3217	<listitem>
3218	<para>
3219	Parse this named.conf to find locations of zones.
3220	</para>
3221	</listitem>
3222	</varlistentry>
3223	<varlistentry>
3224	<term>--on-error-resume-next</term>
3225	<listitem>
3226	<para>
3227	Ignore missing files during parsing. Dangerous.
3228	</para>
3229	</listitem>
3230	</varlistentry>
3231	<varlistentry>
3232	<term>--oracle</term>
3233	<listitem>
3234	<para>
3235	Output in format suitable for the default configuration of the Generic Oracle backend.
3236	</para>
3237	</listitem>
3238	</varlistentry>
3239	<varlistentry>
3240	<term>--slave</term>
3241	<listitem>
3242	<para>
3243	Maintain slave status of zones listed in named.conf as being slaves. The default behaviour is to convert all zones
3244	to native operation.
3245	</para>
3246	</listitem>
3247	</varlistentry>
3248	<varlistentry>
3249	<term>--startid</term>
3250	<listitem>
3251	<para>
3252	Supply a value for the first domain_id generated. Defaults at 0.
3253	</para>
3254	</listitem>
3255	</varlistentry>
3256	<varlistentry>
3257	<term>--transactions</term>
3258	<listitem>
3259	<para>
3260	For Oracle and PostgreSQL output, wrap each domain in a transaction for higher speed and integrity.
3261	</para>
3262	</listitem>
3263	</varlistentry>
3264	<varlistentry>
3265	<term>--verbose</term>
3266	<listitem>
3267	<para>
3268	Be verbose during conversion.
3269	</para>
3270	</listitem>
3271	</varlistentry>
3272	<varlistentry>
3273	<term>--zone=...</term>
3274	<listitem>
3275	<para>
3276	Parse only this zone file. Conflicts with <command>--named-conf</command> parameter.
3277	</para>
3278	</listitem>
3279	</varlistentry>
3280	<varlistentry>
3281	<term>--zone-name=...</term>
3282	<listitem>
3283	<para>
3284	When parsing a single zone without $ORIGIN statement, set this as the zone name.
3285	</para>
3286	</listitem>
3287	</varlistentry>
3288	</variablelist>
3289	</para>
3290	</sect1>
3291	</chapter>
3292
3293	<chapter id="recursion"><title>Recursion</title>
3294
3295	<para>(only available from 1.99.8 and onwards)</para>
3296	<para>
3297	PDNS is an authoritative nameserver. It answers questions with data from its backends. Besides handing out authoritative
3298	answers, DNS also needs so called 'recursion', where a nameserver gets a question for which it has no authoritative answer available,
3299	necessitating questions to other nameservers.
3300	</para>
3301	<para>
3302	Although PDNS is an authoritative nameserver, a provision has been made to cater for installations that require both authoritative DNS
3303	and recursion on one IP address.
3304	</para>
3305	<para>
3306	By specifying the <command>recursor</command> option in the configuration file, questions requiring recursive treatment will be handed over
3307	to the IP address specified. An example configuration might be <command>recursor=130.161.180.1</command>, which designates 130.161.180.1 as
3308	the nameserver to handle recursive queries.
3309	</para>
3310	<para>
3311	Any recursing nameserver is suitable but we highly advise the use of the DJBDNS dnscache (<ULINK URL="http://cr.yp.to/djbdns/dnscache.html" TYPE="alternate">http://cr.yp.to/djbdns/dnscache.html</ULINK>).
3312	</para>
3313	<para>
3314	Take care not to point <command>recursor</command> to PDNS, which leads to a very tight packet loop!
3315	</para>
3316	<para>
3317	By specifying <command>allow-recursion</command>, recursion can be restricted to netmasks specified. The default is to allow
3318	recursion from everywhere. Example: <command>allow-recursion=192.168.0.0/24, 10.0.0.0/8, 1.2.3.4</command>.
3319	</para>
3320	<sect1 id="recursion-details"><title>Details</title>
3321	<para>
3322	Questions carry a number of flags. One of these is called 'Recursion Desired'. If PDNS is configured to allow recursion, AND such a flag
3323	is seen, AND the IP address of the client is allowed to recurse via PDNS, then the packet is handed to the recursing backend.
3324	</para>
3325	<para>
3326	If a Recursion Desired packet PDNS is configured to allow recursion, but not to the IP address of the client, resolution will proceed
3327	as if the RD flag were unset and the answer will indicate that recursion was not available.
3328	</para>
3329	<para>
3330	Recursive questions and answers are not stored in the Packet Cache as recursing backends are generally well equipped to cache questions
3331	themselves.
3332	</para>
3333	<para>
3334	It is also possible to use a resolver living on a different port. To do so, specify a recursor like this:
3335	<command>recursor=130.161.180.1:5300</command>.
3336	</para>
3337	<para>
3338	If the backend does not answer a question within a large amount of time, this is logged as 'Recursive query for remote 10.96.0.2 with internal id 0
3339	was not answered by backend within timeout, reusing id'.
3340	</para>
3341	</sect1>
3342	<sect1 id="lazy-recursion"><title>'Lazy recursion'</title>
3343	<para>
3344	PowerDNS is an authoritative nameserver. Up to version 2.1, a packet indication that recursion was desired, coming from a host from which
3345	recursion was allowed, would be handed sight unseen to the recursing backend. This means that older installations do not have the ability to 'override'
3346	the internet with local data. Recursive queries would not be answered from the database.
3347	</para>
3348	<para>
3349	This behaviour sufficed for many users but some installations have a pressing need to override the internet, for example to support recursive
3350	queries for fake domains like 'powerdns.office' or '.internal'.
3351	</para>
3352	<para>
3353	As of version 2.1, PowerDNS has a feature called 'lazy recursion' where a packet will only be handed to the recursing backend if it cannot be answered
3354	completely from the database. 'Completely' in this case means that the original question has an answer in the local database and any additional processing
3355	can also succeed from the database.
3356	</para>
3357	<para>
3358	So for example, if you have the 'your.office' domain and a query comes in for its MX record, you should locally have the 'your.office' MX record
3359	as well as the IP address of (for example) 'smtp.your.office'.
3360	</para>
3361	<para>
3362	If any of these conditions fail, your packet is handed to the recursor anyhow. So to benefit from lazy-recursion, be very sure that all
3363	data needed is present locally!.
3364	</para>
3365	<para>
3366	To restore pre-2.1 behaviour, specify <command>lazy-recursion=off</command>.
3367	</para>
3368	</sect1>
3369	</chapter>
3370	<chapter id="replication"><title>Master/Slave operation & replication</title>
3371
3372	<para>
3373	PDNS offers full master and slave semantics for replicating domain information. Furthermore, PDNS can benefit from native
3374	database replication.
3375	</para>
3376	<sect1 id="native-replication"><title>Native replication</title>
3377	<para>
3378	Native replication is the default, unless other operation is specifically configured. Native replication basically means that PDNS will
3379	not send out DNS update notifications, nor will react to them. PDNS assumes that the backend is taking care of replication unaided.
3380	</para>
3381	<para>
3382	MySQL replication has proven to be very robust and well suited, even over transatlantic connections between badly peering ISPs. Other PDNS
3383	users employ Oracle replication which also works very well.
3384	</para>
3385	<para>
3386	To use native replication, configure your backend storage to do the replication and do not configure PDNS to do so.
3387	</para>
3388	</sect1>
3389	<sect1 id="slave"><title>Slave operation</title>
3390	<para>
3391	On launch, PDNS requests from all backends a list of domains which have not been checked recently for changes. This should happen every
3392	'<command>refresh</command>' seconds, as specified in the SOA record. All domains that are unfresh are then checked for changes over at their
3393	master. If the <link linkend="soa-type">SOA</link> serial number there is higher, the domain is retrieved and inserted into the database. In
3394	any case, after the check the domain is declared 'fresh', and will only be checked again after '<command>refresh</command>' seconds have passed.
3395	</para>
3396	<para>
3397	PDNS also reacts to notifies by immediately checking if the zone has updated and if so, retransfering it.
3398	</para>
3399	<para>
3400	All backends which implement this feature must make sure that they can handle transactions so as to not leave the zone in a half updated state.
3401	MySQL configured with either BerkeleyDB or InnoDB meets this requirement, as do PostgreSQL and Oracle. The Bindbackend implements transaction
3402	semantics by renaming files if and only if they have been retrieved completely and parsed correctly.
3403	</para>
3404	<sect2 id=supermaster><title>Supermaster automatic provisioning of slaves</title>
3405	<para>
3406	PDNS can recognize so called 'supermasters'. A supermaster is a host which is master for domains and for which we are to be a slave. When
3407	a master (re)loads a domain, it sends out a notification to its slaves. Normally, such a notification is only accepted if PDNS already
3408	knows that it is a slave for a domain.
3409	</para>
3410	<para>
3411	However, a notification from a supermaster carries more persuasion. When PDNS determines that a notification comes from a supermaster and it is
3412	is bonafide, PDNS can provision the domain automatically, and configure itself as a slave for that zone.
3413	</para>
3414	<para>
3415	To enable this feature, a backend needs to know about the IP address of the supermaster, and how PDNS will be listed in the set of
3416	NS records remotely, and the 'account' name of your supermaster. There is no need to fill this out but it does help keep track of
3417	where a domain comes from.
3418	</para>
3419	</sect2>
3420	</sect1>
3421
3422	<sect1 id="master"><title>Master operation</title>
3423	<para>
3424	When operating as a master, PDNS sends out notifications of changes to slaves, which react to these notifications by querying PDNS to see
3425	if the zone changed, and transferring its contents if it has. Notifications are a way to promptly propagate zone changes to slaves, as
3426	described in RFC 1996.
3427	</para>
3428	<para>
3429	Left open by RFC 1996 is who is to be notified - which is harder to figure out than it sounds. All slaves for this domain must receive a notification
3430	but the nameserver only knows the names of the slaves - not the IP addresses, which is where the problem lies. The nameserver itself might
3431	be authoritative for the name of its secondary, but not have the data available.
3432	</para>
3433	<para>
3434	To resolve this issue, PDNS tries multiple tactics to figure out the IP addresses of the slaves, and notifies everybody. In contrived configurations
3435	this may lead to duplicate notifications being sent out, which shouldn't hurt.
3436	</para>
3437	<para>
3438	Some backends may be able to detect zone changes, others may chose to let the operator indicate which zones have changed and which haven't.
3439	Consult the documentation for your backend to see how it processes changes in zones.
3440	</para>
3441	<para>
3442	To help deal with slaves that may have missed notifications, or have failed to respond to them, several override commands are available via
3443	the pdns_control tool (<xref linkend="pdnscontrol">):
3444	</para>
3445	<para>
3446	<variablelist>
3447	<varlistentry>
3448	<term>pdns_control notify <command>domain</command></term>
3449	<listitem>
3450	<para>
3451	This instructs PDNS to notify all IP addresses it considers to be slaves of this domain.
3452	</para>
3453	</listitem>
3454	</varlistentry>
3455	<varlistentry>
3456	<term>pdns_control notify-host <command>domain ip-address</command></term>
3457	<listitem>
3458	<para>
3459	This is truly an override and sends a notification to an arbitrary IP address. Can be used in 'also-notify' situations
3460	or when PDNS has trouble figuring out who to notify - which may happen in contrived configurations.
3461	</para>
3462	</listitem>
3463	</varlistentry>
3464	</variablelist>
3465	</para>
3466	</sect1>
3467	</chapter>
3468	<chapter id="fancy-records"><title>Fancy records for seamless email and URL integration</title>
3469
3470	<para>
3471	PDNS also supports so called 'fancy' records. A Fancy Record is actually not a DNS record, but it is translated into one. Currently,
3472	two fancy records are implemented, but not very useful without additional unreleased software. For completeness, they are listed here.
3473	The software will become available later on and is part of the Express and PowerMail suite of programs.
3474	</para>
3475	<para>
3476	These records imply extra database lookups which has a performance impact. Therefore fancy records are only queried for if they are enabled
3477	with the <command>fancy-records</command> command in <filename>pdns.conf</filename>.
3478	</para>
3479	<para>
3480	<variablelist>
3481	<varlistentry>
3482	<term>MBOXFW</term>
3483	<listitem>
3484	<para>
3485	This record denotes an email forward. A typical entry looks like this:
3486	<screen>
3487	support@yourdomain.com MBOXFW you@yourcompany.com
3488	</screen>
3489	When PDNS encounters a request for an MX record for yourdomain.com it will, if fancy records are enabled, also check for the existence
3490	of an MBOXFW record ending on '@yourdomain.com', in which case it will hand out a record containing the configured
3491	<command>smtpredirector</command>. This server should then also be able to access the PDNS database to figure out where mail to
3492	support@yourdomain.com should go to.
3493	</para>
3494	</listitem>
3495	<varlistentry>
3496	<term>URL</term>
3497	<listitem>
3498	<para>
3499	URL records work in much the same way, but for HTTP. A sample record:
3500	<screen>
3501	yourdomain.com URL http://somewhere.else.com/yourdomain
3502	</screen>
3503	A URL record is converted into an A record containing the IP address configured with the <command>urlredirector</command>
3504	setting. On that IP address a webserver should live that knows how to redirect yourdomain.com to
3505	http://somewhere.else.com/yourdomain.
3506	</para>
3507	</listitem>
3508	</varlistentry>
3509	</variablelist>
3510	</para>
3511	</chapter>
3512	<chapter id="all-settings"><title>Index of all settings</title>
3513	<para>
3514	All PDNS settings are listed here, excluding those that originate from backends, which are documented in the relevant chapters.
3515	<variablelist>
3516	<varlistentry>
3517	<term><anchor id="allow-axfr-ips">allow-axfr-ips=...</term>
3518	<listitem>
3519	<para>When not allowing AXFR (disable-axfr), DO allow from these IP addresses or netmasks.
3520	</para>
3521	</listitem></varlistentry>
3522	<varlistentry>
3523	<term>allow-recursion=...</term>
3524	<listitem>
3525	<para>
3526	By specifying <command>allow-recursion</command>, recursion can be restricted to netmasks specified. The default is to allow
3527	recursion from everywhere. Example: <command>allow-recursion=192.168.0.0/24, 10.0.0.0/8, 1.2.3.4</command>.
3528	</para>
3529	</listitem></varlistentry>
3530	<varlistentry><term>cache-ttl=...</term>
3531	<listitem><para>
3532	Seconds to store packets in the PacketCache. See <xref linkend="packetcache">.
3533	</para></listitem></varlistentry>
3534	<varlistentry><term>chroot=...</term>
3535	<listitem><para>
3536	If set, chroot to this directory for more security. See <xref linkend="security">.
3537	</para></listitem></varlistentry>
3538	<varlistentry><term>config-dir=...</term>
3539	<listitem><para>
3540	Location of configuration directory (pdns.conf)
3541	</para></listitem></varlistentry>
3542	<varlistentry><term>config-name=...</term>
3543	<listitem><para>
3544	Name of this virtual configuration - will rename the binary image. See <xref linkend="virtual">.
3545	</para></listitem></varlistentry>
3546	<varlistentry><term>control-console=...</term>
3547	<listitem><para>
3548	Debugging switch - don't use.
3549	</para></listitem></varlistentry>
3550	<varlistentry><term>daemon=...</term>
3551	<listitem><para>
3552	Operate as a daemon
3553	</para></listitem></varlistentry>
3554	<varlistentry><term>default-soa-name=...</term>
3555	<listitem><para>
3556	name to insert in the SOA record if none set in the backend
3557	</para></listitem></varlistentry>
3558	<varlistentry><term>disable-axfr=...</term>
3559	<listitem><para>
3560	Do not allow zone transfers
3561	</para></listitem></varlistentry>
3562	<varlistentry><term>disable-tcp=...</term>
3563	<listitem><para>
3564	Do not listen to TCP queries. Breaks RFC compliance.
3565	</para></listitem></varlistentry>
3566	<varlistentry><term>distributor-threads=...</term>
3567	<listitem><para>
3568	Default number of Distributor (backend) threads to start. See <xref linkend="performance">.
3569	</para></listitem></varlistentry>
3570	<varlistentry><term>fancy-records=...</term>
3571	<listitem><para>
3572	Process URL and MBOXFW records. See <xref linkend="fancy-records">.
3573	</para></listitem></varlistentry>
3574	<varlistentry><term>guardian \| --guardian=yes \| --guardian=no</term>
3575	<listitem><para>
3576	Run within a guardian process. See <xref linkend="guardian">.
3577	</para></listitem></varlistentry>
3578	<varlistentry><term>help</term>
3579	<listitem><para>
3580	Provide a helpful message
3581	</para></listitem></varlistentry>
3582	<varlistentry><term>launch=...</term>
3583	<listitem><para>
3584	Which backends to launch and order to query them in. See <xref linkend="modules">.
3585	</para></listitem></varlistentry>
3586	<varlistentry><term>lazy-recursion=...</term>
3587	<listitem><para>
3588	On by default as of 2.1. Checks local data first before recursing. See <xref linkend="recursion">.
3589	</para></listitem></varlistentry>
3590	<varlistentry><term>load-modules=...</term>
3591	<listitem><para>
3592	Load this module - supply absolute or relative path. See <xref linkend="modules">.
3593	</para></listitem></varlistentry>
3594	<varlistentry><term>local-address=...</term>
3595	<listitem><para>
3596	Local IP address to which we bind. You can specify multiple addresses separated by commas or whitespace.
3597	</para></listitem></varlistentry>
3598	<varlistentry><term>local-port=...</term>
3599	<listitem><para>
3600	The port on which we listen. Only one port possible.
3601	</para></listitem></varlistentry>
3602	<varlistentry><term><anchor id="log-failed-updates">log-failed-updates=...</term>
3603	<listitem><para>
3604	If set to 'no', failed Windows Dynamic Updates will not be logged.
3605	</para></listitem></varlistentry>
3606	<varlistentry><term><anchor id="log-dns-details">log-dns-details=...</term>
3607	<listitem><para>
3608	If set to 'no', informative-only DNS details will not even be sent to syslog, improving performance. Available from 2.5
3609	and onwards.
3610	</para></listitem></varlistentry>
3611	<varlistentry><term>logging-facility=...</term>
3612	<listitem><para>
3613	If set to a a digit, logging is performed under this LOCAL facility. See <xref linkend="syslog">. Available from 1.99.9 and onwards.
3614	</para></listitem></varlistentry>
3615	<varlistentry><term>loglevel=...</term>
3616	<listitem><para>
3617	Amount of logging. Higher is more. Do not set below 3
3618	</para></listitem></varlistentry>
3619	<varlistentry><term>max-queue-length=...</term>
3620	<listitem><para>
3621	If this many packets are waiting for database attention, consider the situation hopeless and respawn.
3622	</para></listitem></varlistentry>
3623	<varlistentry><term>module-dir=...</term>
3624	<listitem><para>
3625	Default directory for modules. See <xref linkend="modules">.
3626	</para></listitem></varlistentry>
3627	<varlistentry><term>negquery-cache-ttl=...</term>
3628	<listitem><para>
3629	Seconds to store queries with no answer in the Query Cache. See <xref linkend="querycache">.
3630	</para></listitem></varlistentry>
3631	<varlistentry><term>no-config</term>
3632	<listitem><para>
3633	Do not attempt to read the configuration file.
3634	</para></listitem></varlistentry>
3635	<varlistentry><term>out-of-zone-additional-processing \| --out-of-zone-additional-processing=yes \| --out-of-zone-additional-processing=no</term>
3636	<listitem><para>
3637	Do out of zone additional processing
3638	</para></listitem></varlistentry>
3639	<varlistentry><term>query-cache-ttl=...</term>
3640	<listitem><para>
3641	Seconds to store queries with an answer in the Query Cache. See <xref linkend="querycache">.
3642	</para></listitem></varlistentry>
3643	<varlistentry><term>queue-limit=...</term>
3644	<listitem><para>
3645	Maximum number of miliseconds to queue a query. See <xref linkend="performance">.
3646	</para></listitem></varlistentry>
3647	<varlistentry><term>query-logging \| query-logging=yes \| query-logging=no</term>
3648	<listitem><para>
3649	Hints to a backend that it should log a textual representation of queries it performs. Can be set at runtime.
3650	</para></listitem></varlistentry>
3651	<varlistentry><term>recursive-cache-ttl=...</term>
3652	<listitem><para>
3653	Seconds to store recursive packets in the PacketCache. See <xref linkend="packetcache">.
3654	</para></listitem></varlistentry>
3655	<varlistentry><term>recursor=...</term>
3656	<listitem><para>
3657	If set, recursive queries will be handed to the recursor specified here. See <xref linkend="recursion">.
3658	</para></listitem></varlistentry>
3659	<varlistentry><term>setgid=...</term>
3660	<listitem><para>
3661	If set, change group id to this gid for more security. See <xref linkend="security">.
3662	</para></listitem></varlistentry>
3663	<varlistentry><term>setuid=...</term>
3664	<listitem><para>
3665	If set, change user id to this uid for more security. See <xref linkend="security">.
3666	</para></listitem></varlistentry>
3667	<varlistentry><term>skip-cname \| --skip-cname=yes \| --skip-cname=no</term>
3668	<listitem><para>
3669	Do not perform CNAME indirection for each query. Has performance implications. See <xref linkend="security">.
3670	</para></listitem></varlistentry>
3671	<varlistentry><term>slave-cycle-interval=60</term>
3672	<listitem><para>
3673	Schedule slave up-to-date checks of domains whose status is unknown every .. seconds. See <xref linkend="fancy-records">.
3674	</para></listitem></varlistentry>
3675	<varlistentry><term>smtpredirector=...</term>
3676	<listitem><para>
3677	Our smtpredir MX host. See <xref linkend="fancy-records">.
3678	</para></listitem></varlistentry>
3679	<varlistentry><term>soa-serial-offset=...</term>
3680	<listitem><para>
3681	If your database contains single-digit SOA serials and you need to host .DE domains, this setting can help
3682	placate their 6-digit SOA serial requirements. Suggested value is to set this to 1000000 which adds 1000000 to all SOA Serials
3683	under that offset.
3684	</para></listitem></varlistentry>
3685	<varlistentry><term>socket-dir=...</term>
3686	<listitem><para>
3687	Where the controlsocket will live. See <xref linkend="controlsocket">.
3688	</para></listitem></varlistentry>
3689	<varlistentry><term>strict-rfc-axfrs \| --strict-rfc-axfrs=yes \| --strict-rfc-axfrs=no</term>
3690	<listitem><para>
3691	Perform strictly RFC conformant AXFRs, which are slow, but needed to placate some old client tools.
3692	</para></listitem></varlistentry>
3693	<varlistentry><term>urlredirector=...</term>
3694	<listitem><para>
3695	Where we send hosts to that need to be url redirected. See <xref linkend="fancy-records">.
3696	</para></listitem></varlistentry>
3697	<varlistentry><term>webserver \| --webserver=yes \| --webserver=no</term>
3698	<listitem><para>
3699	Start a webserver for monitoring. See <xref linkend="monitoring">.
3700	</para></listitem></varlistentry>
3701	<varlistentry><term>webserver-address=...</term>
3702	<listitem><para>
3703	IP Address of webserver to listen on. See <xref linkend="monitoring">.
3704	</para></listitem></varlistentry>
3705	<varlistentry><term>webserver-password=...</term>
3706	<listitem><para>
3707	Password required for accessing the webserver. See <xref linkend="monitoring">.
3708	</para></listitem></varlistentry>
3709	<varlistentry><term>webserver-port=...</term>
3710	<listitem><para>
3711	Port of webserver to listen on. See <xref linkend="monitoring">.
3712	</para></listitem></varlistentry>
3713	<varlistentry><term>wildcard-url=...</term>
3714	<listitem><para>
3715	Check for wildcard URL records.
3716	</para></listitem></varlistentry>
3717	<varlistentry><term>wildcards=...</term>
3718	<listitem><para>
3719	Honor wildcards in the database. On by default. Turning this off has performance implications, see <xref linkend="performance">.
3720	</para></listitem></varlistentry>
3721	</variablelist>
3722	</para>
3723	</chapter>
3724	<chapter id="metrics"><title>Index of all internal metrics</title>
3725	<para></para>
3726	<sect1 id="counters-variables"><title>Counters & variables</title>
3727	<para>
3728	A number of counters and variables are set during PDNS operation. These can be queried with the init.d
3729	<command>dump</command>, <command>show</command> and <command>mrtg</command> commands, or viewed with the
3730	webserver.
3731
3732	<variablelist>
3733	<varlistentry>
3734	<term>corrupt-packets</term>
3735	<listitem><para>Number of corrupt packets received</para></listitem>
3736	</varlistentry>
3737	<varlistentry>
3738	<term>latency</term>
3739	<listitem><para>Average number of microseconds a packet spends within PDNS</para></listitem>
3740	</varlistentry>
3741	<varlistentry>
3742	<term>packetcache-hit</term>
3743	<listitem><para>Number of packets which were answered out of the cache</para></listitem>
3744	</varlistentry>
3745	<varlistentry>
3746	<term>packetcache-miss</term>
3747	<listitem><para>Number of times a packet could not be answered out of the cache</para></listitem>
3748	</varlistentry>
3749	<varlistentry>
3750	<term>packetcache-size</term>
3751	<listitem><para>Amount of packets in the packetcache</para></listitem>
3752	</varlistentry>
3753	<varlistentry>
3754	<term>qsize-a</term>
3755	<listitem><para>Size of the queue before the transmitting socket.</para></listitem>
3756	</varlistentry>
3757	<varlistentry>
3758	<term>qsize-q</term>
3759	<listitem><para>Number of packets waiting for database attention</para></listitem>
3760	</varlistentry>
3761	<varlistentry>
3762	<term>servfail-packets</term>
3763	<listitem><para>Amount of packets that could not be answered due to database problems</para></listitem>
3764	</varlistentry>
3765	<varlistentry>
3766	<term>tcp-answers</term>
3767	<listitem><para>Number of answers sent out over TCP</para></listitem>
3768	</varlistentry>
3769	<varlistentry>
3770	<term>tcp-questions</term>
3771	<listitem><para>Number of questions received over TCP</para></listitem>
3772	</varlistentry>
3773	<varlistentry>
3774	<term>timedout-questions</term>
3775	<listitem><para>Amount of packets that were dropped because they had to wait too long internally</para></listitem>
3776	</varlistentry>
3777	<varlistentry>
3778	<term>udp-answers</term>
3779	<listitem><para>Number of answers sent out over UDP</para></listitem>
3780	</varlistentry>
3781	<varlistentry>
3782	<term>udp-questions</term>
3783	<listitem><para>Number of questions received over UDP</para></listitem>
3784	</varlistentry>
3785	</variablelist>
3786	</para>
3787	<para>
3788	<sect2><title>Ring buffers</title>
3789	<para>
3790	Besides counters, PDNS also maintains the ringbuffers. A ringbuffer records events, each new event gets a place
3791	in the buffer until it is full. When full, earlier entries get overwritten, hence the name 'ring'.
3792	</para>
3793	<para>
3794	By counting the entries in the buffer, statistics can be generated. These statistics can currently only be viewed
3795	using the webserver and are in fact not even collected without the webserver running.
3796	</para>
3797	<para>
3798	The following ringbuffers are available:
3799	</para>
3800	<para>
3801	<variablelist>
3802	<varlistentry>
3803	<term>Log messages (logmessages)</term>
3804	<listitem><para>All messages logged</para></listitem>
3805	</varlistentry>
3806	<varlistentry>
3807	<term>Queries for existing records but for a type we don't have (noerror-queries)</term>
3808	<listitem><para>Queries for, say, the AAAA record of a domain, when only an A is available.
3809	Queries are listed in the following format: name/type. So an AAA query for pdns.powerdns.com looks like
3810	pdns.powerdns.com/AAAA.</para></listitem>
3811	</varlistentry>
3812	<varlistentry>
3813	<term>Queries for non-existing records within existing domains(nxdomain-queries)</term>
3814	<listitem><para>If PDNS knows it is authoritative over a domain, and it sees a question for a record in that domain
3815	that does not exist, it is able to send out an authoritative 'no such domain' message. Indicates that hosts are
3816	trying to connect to services really not in your zone.</para></listitem>
3817	</varlistentry>
3818
3819	<varlistentry>
3820	<term>UDP queries received (udp-queries)</term>
3821	<listitem><para>
3822	All UDP queries seen.
3823	</para></listitem>
3824	</varlistentry>
3825	<varlistentry>
3826	<term>Remote server IP addresses (remotes)</term>
3827	<listitem><para>
3828	Hosts querying PDNS. Be aware that UDP is anonymous - person A can send queries that appear to be coming from
3829	person B.
3830	</para></listitem>
3831	</varlistentry>
3832	<varlistentry>
3833	<term>Remotes sending corrupt packets (remote-corrupts)</term>
3834	<listitem><para>
3835	Hosts sending PDNS broken packets, possibly meant to disrupt service. Be aware that UDP is
3836	anonymous - person A can send queries that appear to be coming from person B.
3837	</para></listitem>
3838	</varlistentry>
3839	<varlistentry>
3840	<term>Remotes querying domains for which we are not auth (remote-unauth)</term>
3841	<listitem><para>
3842	It may happen that there are misconfigured hosts on the internet which are configured to
3843	think that a PDNS installation is in fact a resolving nameserver. These hosts will not
3844	get useful answers from PDNS. This buffer lists hosts sending queries for domains which
3845	PDNS does not know about.
3846	</para></listitem>
3847	</varlistentry>
3848	<varlistentry>
3849	<term>Queries that could not be answered due to backend errors (servfail-queries)</term>
3850	<listitem><para>
3851	For one reason or another, a backend may be unable to extract answers for a certain domain from
3852	its storage. This may be due to a corrupt database or to inconsistent data. When this happens,
3853	PDNS sends out a 'servfail' packet indicating that it was unable to answer the question. This buffer
3854	shows which queries have been causing servfails.
3855	</para></listitem>
3856	</varlistentry>
3857	<varlistentry>
3858	<term>Queries for domains that we are not authoritative for (unauth-queries)</term>
3859	<listitem><para>
3860	If a domain is delegated to a PDNS instance, but the backend is not made aware of this fact, questions come
3861	in for which no answer is available, nor is the authority. Use this ringbuffer to spot such queries.
3862	</para></listitem>
3863	</varlistentry>
3864	</variablelist>
3865	</para>
3866	</chapter>
3867
3868	<chapter id="types"><title>Supported record types and their storage</title>
3869	<para>
3870	This chapter lists all record types PDNS supports, and how they are stored in backends. The list is mostly alphabetical but
3871	some types are grouped.
3872	<variablelist>
3873	<varlistentry>
3874	<term>A</term>
3875	<listitem>
3876	<para>
3877	The A record contains an IP address. It is stored as a decimal dotted quad string,
3878	for example: '213.244.168.210'.
3879	</para>
3880	</listitem>
3881	</varlistentry>
3882	<varlistentry>
3883	<term>AAAA</term>
3884	<listitem>
3885	<para>
3886	The AAAA record contains an IPv6 address. It is stored as a decimal dotted quad string,
3887	for example: '3ffe:8114:2000:bf0::1'.
3888	</para>
3889	</listitem>
3890	</varlistentry>
3891	<varlistentry>
3892	<term>CNAME</term>
3893	<listitem>
3894	<para>
3895	The CNAME record specifies the canonical name of a record. It is stored plainly. Like all other records, it is not
3896	terminated by a dot. A sample might be 'webserver-01.yourcompany.com'.
3897	</para>
3898	</listitem>
3899	</varlistentry>
3900	<varlistentry>
3901	<term>HINFO</term>
3902	<listitem>
3903	<para>
3904	Hardware Info record, used to specify CPU and operating system. Stored with a single space separating these two,
3905	example: 'i386 Linux'.
3906	</para>
3907	</listitem>
3908	</varlistentry>
3909	<varlistentry>
3910	<term>MX</term>
3911	<listitem>
3912	<para>
3913	The MX record specifies a mail exchanger host for a domain. Each mail exchanger also has a priority or preference.
3914	This should be specified in the separate field dedicated for that purpose, often called 'prio'.
3915	</para>
3916	</listitem>
3917	</varlistentry>
3918	<varlistentry>
3919	<term><anchor id="naptr">NAPTR</term>
3920	<listitem>
3921	<para>
3922
3923	Naming Authority Pointer, RFC 2915. Stored as follows:
3924	<screen>
3925	'100 50 "s" "z3950+I2L+I2C" "" _z3950._tcp.gatech.edu'.
3926	</screen>
3927	The fields are: order, preference, flags, service, regex,
3928	replacement. Note that the replacement is not enclosed in quotes, and should not be. The replacement may be omitted, in which
3929	case it is empty. See also RFC 2916 for how to use NAPTR for ENUM (E.164) purposes.
3930	</para>
3931	</listitem>
3932	</varlistentry>
3933	<varlistentry>
3934	<term>NS</term>
3935	<listitem>
3936	<para>
3937	Nameserver record. Specifies nameservers for a domain. Stored plainly: 'ns1.powerdns.com', as always without a terminating dot.
3938	</para>
3939	</listitem>
3940	</varlistentry>
3941	<varlistentry>
3942	<term>PTR</term>
3943	<listitem>
3944	<para>
3945	Reverse pointer, used to specify the host name belonging to an IP or IPv6 address. Name is stored plainly: 'www.powerdns.com'.
3946	As always, no terminating dot.
3947	</para>
3948	</listitem>
3949	</varlistentry>
3950	<varlistentry>
3951	<term>RP</term>
3952	<listitem>
3953	<para>
3954	Responsible Person record, as described in RFC 1183. Stored with a single space between the mailbox name and the more-information
3955	pointer. Example 'peter.powerdns.com peter.people.powerdns.com', to indicate that peter@powerdns.com is responsible and that more
3956	information about peter is available by querying the TXT record of peter.people.powerdns.com.
3957	</para>
3958	</listitem>
3959	</varlistentry>
3960	<varlistentry>
3961	<term><anchor id="soa-type">SOA</term>
3962	<listitem>
3963	<para>
3964	The Start of Authority record is one of the most complex available. It specifies a lot about a domain: the name
3965	of the master nameserver ('the primary'), the hostmaster and a set of numbers indicating how the data in this domain
3966	expires and how often it needs to be checked. Further more, it contains a serial number which should rise on each change
3967	of the domain.
3968	</para>
3969	<para>
3970	The stored format is:
3971	<screen>
3972	primary hostmaster serial refresh retry expire default_ttl
3973	</screen>
3974	Besides the primary and the hostmaster, all fields are numerical. PDNS has a set of default values:
3975	<table>
3976	<title>SOA fields</title>
3977	<tgroup cols=2>
3978	<tbody>
3979	<row>
3980	<entry>primary</entry><entry><command>default-soa-name</command> configuration option</entry>
3981	</row>
3982	<row>
3983	<entry>hostmaster</entry><entry>hostmaster@domain-name</entry>
3984	</row>
3985	<row>
3986	<entry>serial</entry><entry>0</entry>
3987	</row>
3988	<row>
3989	<entry>refresh</entry><entry>10800 (3 hours)</entry>
3990	</row>
3991	<row>
3992	<entry>retry</entry><entry>3600 (1 hour)</entry>
3993	</row>
3994	<row>
3995	<entry>expire</entry><entry>604800 (1 week)</entry>
3996	</row>
3997	<row>
3998	<entry>default_ttl</entry><entry>3600 (1 hour)</entry>
3999	</row>
4000	</tbody>
4001	</tgroup>
4002	</table>
4003	</para>
4004	<para>
4005	The fields have complicated and sometimes controversial meanings. The 'serial' field is special. If left at 0, the default,
4006	PDNS will perform an internal list of the domain to determine highest change_date field of all records within the zone, and use
4007	that as the zone serial number. This means that the serial number is always raised when changes are made to the zone, as long
4008	as the change_date field is being set.
4009	</para>
4010	</listitem>
4011	</varlistentry>
4012	<varlistentry>
4013	<term>TXT</term>
4014	<listitem>
4015	<para>
4016	The TXT field can be used to attach textual data to a domain. Text is stored plainly.
4017	</para>
4018	</listitem>
4019	</varlistentry>
4020	</variablelist>
4021	</para>
4022	</chapter>
4023	<chapter id="faq"><title>HOWTO & Frequently Asked Questions</title>
4024	<para>
4025	This chapter contains a number of FAQs and HOWTOs.
4026	</para>
4027	<sect1 id="pdns-devel-faq"><title>Backend developer HOWTO</title>
4028	<para>
4029	Writing backends without access to the full PDNS source means that you need to write code that can be loaded by PDNS at runtime.
4030	This in turn means that you need to use the same compiler that we do. For linux, this is currently GCC 3.0.4, although any 3.0.x
4031	compiler is probably fine. In tests, even 3.1 works.
4032	</para>
4033	<para>
4034	For FreeBSD we use GCC 2.95.2.
4035	</para>
4036	<para>
4037	Furthermore, your pdns_server executable must be dynamically linked. The default .rpm PDNS contains a static binary so you need to retrieve the
4038	dynamic rpm or the dynamic tar.gz or the Debian unstable ('Woody') deb. FreeBSD dynamic releases are forthcoming.
4039	</para>
4040	<variablelist>
4041	<varlistentry>
4042	<term>Q: Will PDNS drivers work with other PDNS versions than they were compiled for?</term>
4043	<listitem>
4044	<para>
4045	A: 'Probably'. We make no guarantees. Efforts have been made to keep the interface between the backend and PDNS as thin
4046	as possible. For example, a backend compiled with the 1.99.11 backend development kit works with 1.99.10. But don't count on it.
4047	We will notify when we think an incompatible API change has occured but you are best off recompiling your driver for each
4048	new PDNS release.
4049	</para>
4050	</listitem>
4051	</varlistentry>
4052	<varlistentry>
4053	<term>Q: What is in that DNSPacket * pointer passed to lookup!</term>
4054	<listitem>
4055	<para>
4056	A: For reasons outlined above, you should treat that pointer as opaque and only access it via the <function>getRemote()</function>
4057	functions made available and documented above. The DNSPacket class changes a lot and this level of indirection allows for greater
4058	changes to be made without changing the API to the backend coder.
4059	</para>
4060	</listitem>
4061	</varlistentry>
4062	<varlistentry>
4063	<term>Q: How is the PowerDNS Open Source Backend Development Kit licensed?</term>
4064	<listitem>
4065	<para>
4066	A: MIT X11, a very liberal license permitting basically everything.
4067	</para>
4068	</listitem>
4069	</varlistentry>
4070	<varlistentry>
4071	<term>Q: Can I release the backend I wrote?</term>
4072	<listitem>
4073	<para>
4074	A: Please do! If you tell us about it we will list you on our page.
4075	</para>
4076	</listitem>
4077	</varlistentry>
4078	<varlistentry>
4079	<term>Q: Can I sell backends I wrote?</term>
4080	<listitem>
4081	<para>
4082	A: You can. Again, if you tell us about them we will list your backend on the site. You can keep the source of your backend
4083	secret if you want, or you can share it with the world under any license of your chosing.
4084	</para>
4085	</listitem>
4086	</varlistentry>
4087	<varlistentry>
4088	<term>Q: Will PowerDNS use my code in the PDNS distribution?</term>
4089	<listitem>
4090	<para>
4091	A: If your license permits it and we like your backend, we sure will. If your license does not permit it but we like your
4092	backend anyway we may contact you.
4093	</para>
4094	</listitem>
4095	</varlistentry>
4096	<varlistentry>
4097	<term>Q: My backend compiles but when I try to load it, it says 'undefined symbol: _Z13BackendMakersv'</term>
4098	<listitem>
4099	<para>
4100	A: Your pdns_server binary is static and cannot load a backend driver at runtime. Get a dynamic version of pdns, or complain
4101	to pdns@powerdns.com if one isn't available. To check what kind of binary you have, execute 'file $(which pdns_server)'.
4102	</para>
4103	</listitem>
4104	</varlistentry>
4105	<varlistentry>
4106	<term>Q: My backend compiles but when I try to load it, it says 'undefined symbol: BackendMakers__Fv'</term>
4107	<listitem>
4108	<para>
4109	A: You compiled with the wrong GCC. Use GCC 3.x for Linux, 2.95.x for FreeBSD. You may want to change g++ to g++-3.0 in the Makefile,
4110	or change your path so that 3.x is used.
4111	</para>
4112	</listitem>
4113	</varlistentry>
4114	<varlistentry>
4115	<term>Q: I downloaded a dynamic copy of pdns_server but it doesn't run, even without my backend</term>
4116	<listitem>
4117	<para>
4118	A: Run 'ldd' on the pdns_server binary and figure out what libraries you are missing. Most likely you need to install gcc 3.0 libraries,
4119	RedHat 7.1 and 7.2 have packages available, Debian installs these by default if you use the 'unstable deb' of PDNS.
4120	</para>
4121	</listitem>
4122	</varlistentry>
4123	<varlistentry>
4124	<term>Q: What I want can't be done from a backend - I need the whole PDNS source</term>
4125	<listitem>
4126	<para>
4127	A: If you require the source, please contact us (pdns@powerdns.com). All commercial licensees receive the source,
4128	for others we may grant exceptions.
4129	</para>
4130	</listitem>
4131	</varlistentry>
4132	<varlistentry>
4133	<term>Q: What is this 'AhuException' I keep reading about?</term>
4134	<listitem>
4135	<para>
4136	A: This name has historical reasons and has <ulink url="http://ds9a.nl">no significance</ulink>.
4137	</para>
4138	</listitem>
4139	</varlistentry>
4140	<varlistentry>
4141	<term>Q: I need a backend but I can't write it, can you help?</term>
4142	<listitem>
4143	<para>
4144	A: Yes, we also do custom development. Contact us at pdns@powerdns.com.
4145	</para>
4146	</listitem>
4147	</varlistentry>
4148
4149	</variablelist>
4150	</sect1>
4151	<sect1 id="powerdns-company-faq"><title>About PowerDNS.COM BV, 'the company'</title>
4152	<para>
4153	As of 25 November 2002, the PowerDNS nameserver and its modules are open source. This has led to a lot of questions on the future
4154	of both PowerDNS, the company and the products. This FAQ attempts to address these questions.
4155	</para>
4156	<para>
4157	<variablelist>
4158	<varlistentry>
4159	<term>Q: Is PowerDNS 2.9 really open source? What license?</term>
4160	<listitem>
4161	<para>
4162	A: PowerDNS 2.9 is licensed under the GNU General Public License version two, the same license that covers the Linux kernel.
4163	</para>
4164	</listitem>
4165	</varlistentry>
4166	<varlistentry>
4167	<term>Q: Is the open source version crippled?</term>
4168	<listitem>
4169	<para>
4170	A: It is not. Not a single byte has been omitted.
4171	</para>
4172	</listitem>
4173	</varlistentry>
4174	<varlistentry>
4175	<term>Q: Is the nameserver abandoned?</term>
4176	<listitem>
4177	<para>
4178	A: Far from it. In fact, we expect development to speed up now that we have joined the open source community.
4179	</para>
4180	</listitem>
4181	</varlistentry>
4182	<varlistentry>
4183	<term>Q: Why is the nameserver now open source?</term>
4184	<listitem>
4185	<para>
4186	A: In the current economic climate and also the way the Internet is built up right now, selling software is very hard. Most potential
4187	customers had never before bought a piece of software for their UNIX internet setup. Even though we know (from the recent survey) that
4188	nameserver operators love PowerDNS, their suggested price for it is in the $100 range.
4189	</para>
4190	<para>
4191	For us, it makes far more sense to open source PowerDNS than to ask $100 for it. It is expected that open sourcing PowerDNS will lead
4192	to far higher adoption rates. We hope that PowerDNS will soon be included in major Linux and UNIX distributions.
4193	</para>
4194	</listitem>
4195	<varlistentry>
4196	<term>Q: How does PowerDNS.COM BV expect to make money now that the nameserver is free?</term>
4197	<listitem>
4198	<para>
4199	A: In fact, we don't expect to in the near future. We also don't have a lot of expenses, basically
4200	some hosting and a few domain names.
4201	</para>
4202	<para>
4203	However, we are available for consulting work, for example to help a large registrar or registry migrate to PowerDNS, or to help
4204	integrate our software in existing provisioning systems.
4205	</para>
4206	<para>
4207	Furthermore, non-GPL licenses are available for those needing to do closed source modifications, or for customers
4208	uncomfortable with the GPL. This is much like what <ulink url="http://www.mysql.com/company/index.html">MySQL AB</ulink> is doing now.
4209	</para>
4210	<para>
4211	In fact, their strategy is a lot like ours in general.
4212	</para>
4213	</varlistentry>
4214	<varlistentry>
4215	<term>Q: Can I buy support contracts for PowerDNS?</term>
4216	<listitem>
4217	<para>
4218	Sure, to do so, please contact us at <email>sales@powerdns.com</email>
4219	</para>
4220	</varlistentry>
4221	<varlistentry>
4222	<term>Q: Will you accept patches? We've added a feature</term>
4223	<listitem>
4224	<para>
4225	Probably - in general, it is best to discuss your intentions and needs on the <email>pdns-dev@mailman.powerdns.com</email> (<ulink url="http://mailman.powerdns.com/mailman/listinfo/pdns-dev">subscribe</ulink>)
4226	mailinglist
4227	before doing the work. We may have suggestions or guidelines on how you should implement the feature.
4228	</para>
4229	</listitem>
4230	</varlistentry>
4231	<varlistentry>
4232	<term>Q: PowerDNS doesn't work on my platform, will you port it?</term>
4233	<term>Q: PowerDNS doesn't have feature I need, will you add it?</term>
4234	<listitem>
4235	<para>
4236	Be sure to ask on the <email>pdns-dev@mailman.powerdns.com</email> (<ulink url="http://mailman.powerdns.com/mailman/listinfo/pdns-dev">subscribe</ulink>) mailinglist. You can even hire us to do work on PowerDNS
4237	if plain asking is not persuasive enough. This might be the case if we don't currently have time for your feature, but you
4238	need it quickly anyhow, and are not in a position to submit a patch implementing it.
4239	</para>
4240	</listitem>
4241	</varlistentry>
4242	<varlistentry>
4243	<term>Q: Will <ulink url="http://express.powerdns.com">PowerDNS Express</ulink> be open sourced?
4244	<ulink url="http://www.powerdns.com/powermail/">PowerMail?</ulink></term>
4245	<listitem>
4246	<para>
4247	Perhaps, we're not yet sure. PowerMail most probably.
4248	</para>
4249	</listitem>
4250	</varlistentry>
4251
4252	<varlistentry>
4253	<term>Q: We are a Linux/Unix vendor, can we include PowerDNS?
4254	<listitem>
4255	<para>
4256	A: Please do. In fact, we'd be very happy to work with you to make this happen. Contact <email>ahu@ds9a.nl</email>
4257	if you have specific upstream needs.
4258	</para>
4259	</listitem>
4260	</varlistentry>
4261	</variablelist>
4262	</para>
4263	</sect1>
4264	</chapter>
4265	<Appendix id="backends-detail"><title>Backends in detail</title>
4266	<para>
4267	This appendix lists several of the available backends in more detail
4268	</para>
4269
4270
4271	<sect1 id="pipebackend"><title>PipeBackend</title>
4272	<para>
4273	<table>
4274	<title>PipeBackend capabilities</title>
4275	<tgroup cols=2>
4276	<tbody>
4277	<row><entry>Native</entry><entry>Yes</entry></row>
4278	<row><entry>Master</entry><entry>No</entry></row>
4279	<row><entry>Slave</entry><entry>No</entry></row>
4280	<row><entry>Superslave</entry><entry>No</entry></row>
4281	<row><entry>Autoserial</entry><entry>No</entry></row>
4282	<row><entry>Case</entry><entry>Depends</entry></row>
4283	</tbody>
4284	</tgroup>
4285	</table>
4286	</para>
4287	<para>
4288	The PipeBackend allows for easy dynamic resolution based on a 'Coprocess' which can be written in any
4289	programming language that can read a question on standard input and answer on standard output.
4290	</para>
4291	<para>
4292	To configure, the following settings are available:
4293	<variablelist>
4294	<varlistentry>
4295	<term>pipe-command</term>
4296	<listitem>
4297	<para>
4298	Command to launch as backend. Mandatory.
4299	</para>
4300	</listitem>
4301	</varlistentry>
4302	<varlistentry>
4303	<term>pipe-timeout</term>
4304	<listitem>
4305	<para>
4306	Number of milliseconds to wait for an answer from the backend. If this time is ever exceeded, the backend
4307	is declared dead and a new process is spawned. Available since 2.7.
4308	</para>
4309	</listitem>
4310	</varlistentry>
4311	<varlistentry>
4312	<term>pipe-regex</term>
4313	<listitem>
4314	<para>
4315	If set, only questions matching this regular expression are even sent to the backend. This makes sure that
4316	most of PowerDNS does not slow down if you you reploy a slow backend. A query for the A record of 'www.powerdns.com'
4317	would be presented to the regex as 'www.powerdns.com;A'. A matching regex would be '^www.powerdns.com;.*$'.
4318	</para>
4319	<para>
4320	To match only ANY and A queries for www.powerdns.com, use '^www.powerdns.com;(A\|ANY)$'. Available since 2.8.
4321	</para>
4322	</listitem>
4323	</varlistentry>
4324	</variablelist>
4325	</para>
4326
4327	<sect2 id="pipebackend-protocol"><title>PipeBackend protocol</title>
4328	<para>
4329	Questions come in over a file descriptor, by default standard input. Answers
4330	are sent out over another file descriptor, standard output by default.
4331	</para>
4332	<sect3>
4333	<title>Handshake</title>
4334	<para>
4335	PowerDNS sends out 'HELO\t1', indicating that it wants to speak the
4336	protocol as defined in this document, version 1.
4337
4338	A PowerDNS CoProcess must then send out a banner, prefixed by 'OK\t',
4339	indicating it launched successfully. If it does not support the indicated
4340	version, it should respond with FAIL, but not exit. Suggested behaviour is
4341	to try and read a further line, and wait to be terminated.
4342	</para></sect3>
4343	<sect3><title>Questions</title>
4344	<para>
4345	Questions come in three forms and are prefixed by a tag indicating the kind:
4346	<variablelist>
4347	<varlistentry>
4348	<term>Q</term>
4349	<listitem>
4350	<para>
4351	Regular queries
4352	</para>
4353	</listitem>
4354	</varlistentry>
4355	<varlistentry>
4356	<term>AXFR</term>
4357	<listitem>
4358	<para>
4359	List requests, which mean that an entire zone should be listed
4360	</para>
4361	</listitem>
4362	</varlistentry>
4363	<varlistentry>
4364	<term>PING</term>
4365	<listitem>
4366	<para>
4367	Check if the coprocess is functioning
4368	</para>
4369	</listitem>
4370	</varlistentry>
4371	</variablelist>
4372	The question format:
4373	<screen>
4374	type qname qclass qtype id ip-address
4375	</screen>
4376
4377	Fields are tab separated, and terminated with a single \n.
4378
4379	Type is the tag above, qname is the domain the question is about. qclass is
4380	always 'IN' currently, denoting an INternet question. qtype is the kind of
4381	information desired, the record type, like A, CNAME or AAAA. id can be
4382	specified to help your backend find an answer if the id is already known
4383	from an earlier query. You can ignore it.
4384
4385	ip-address is the ip-address of the nameserver asking the question.
4386	</para></sect3>
4387	<sect3><title>Answers</title>
4388	<para>
4389
4390	Each answer starts with a tag, possibly followed by a TAB and more data.
4391	<variablelist>
4392	<varlistentry>
4393	<term>DATA</term>
4394	<listitem>
4395	<para>
4396	Indicating a successful line of DATA
4397	</para>
4398	</listitem>
4399	</varlistentry>
4400	<varlistentry>
4401	<term>END</term>
4402	<listitem>
4403	<para>
4404	Indicating the end of an answer - no further data
4405	</para>
4406	</listitem>
4407	</varlistentry>
4408	<varlistentry>
4409	<term>FAIL</term>
4410	<listitem>
4411	<para>
4412	Indicating a lookup failure. Also serves as 'END'. No further data.
4413	</para>
4414	</listitem>
4415	</varlistentry>
4416	<varlistentry>
4417	<term>LOG</term>
4418	<listitem>
4419	<para>
4420	For specifying things that should be logged. Can only be sent after
4421	a query and before an END line. After the tab, the message to be
4422	logged
4423
4424	</para>
4425	</listitem>
4426	</varlistentry>
4427	</variablelist>
4428
4429
4430	So letting it be known that there is no data consists if sending 'END'
4431	without anything else.
4432
4433
4434	The answer format:
4435	<screen>
4436	DATA qname qclass qtype ttl id content
4437	</screen>
4438
4439	'content' is as specified in <xref linkend="types">.
4440
4441	A sample dialogue may look like this:
4442	<screen>
4443	Q www.ds9a.nl IN CNAME -1 213.244.168.210
4444	DATA www.ds9a.nl IN CNAME 3600 1 ws1.ds9a.nl
4445	Q ws1.ds9a.nl IN CNAME -1 213.244.168.210
4446	END
4447	Q wd1.ds9a.nl IN A -1 213.244.168.210
4448	DATA ws1.ds9a.nl IN A 3600 1 1.2.3.4
4449	DATA ws1.ds9a.nl IN A 3600 1 1.2.3.5
4450	DATA ws1.ds9a.nl IN A 3600 1 1.2.3.6
4451	END
4452	</screen>
4453
4454	This would correspond to a remote webserver 213.244.168.210 wanting to
4455	resolve the IP address of www.ds9a.nl, and PowerDNS traversing the CNAMEs to
4456	find the IP addresses of ws1.ds9a.nl
4457
4458	Another dialogue might be:
4459	<screen>
4460	Q ds9a.nl IN SOA -1 213.244.168.210
4461	DATA ds9a.nl IN SOA 86400 1 ahu.ds9a.nl ...
4462	END
4463	AXFR 1
4464	DATA ds9a.nl IN SOA 86400 1 ahu.ds9a.nl ...
4465	DATA ds9a.nl IN NS 86400 1 ns1.ds9a.nl
4466	DATA ds9a.nl IN NS 86400 1 ns2.ds9a.nl
4467	DATA ns1.ds9a.nl IN A 86400 1 213.244.168.210
4468	DATA ns2.ds9a.nl IN A 86400 1 63.123.33.135
4469	.
4470	.
4471	END
4472	</screen>
4473
4474	This is a typical zone transfer.
4475	</para>
4476	</sect3>
4477	<sect3>
4478	<title>Sample perl backend</title>
4479	<para>
4480	<screen>
4481	#!/usr/bin/perl -w
4482	# sample PowerDNS Coprocess backend
4483	#
4484
4485	use strict;
4486
4487
4488	$\|=1; # no buffering
4489
4490	my $line=<>;
4491	chomp($line);
4492
4493	unless($line eq "HELO\t1") {
4494	print "FAIL\n";
4495	print STDERR "Recevied '$line'\n";
4496	<>;
4497	exit;
4498	}
4499	print "OK Sample backend firing up\n"; # print our banner
4500
4501	while(<>)
4502	{
4503	print STDERR "$$ Received: $_";
4504	chomp();
4505	my @arr=split(/\t/);
4506	if(@arr<6) {
4507	print "LOG PowerDNS sent unparseable line\n";
4508	print "FAIL\n";
4509	next;
4510	}
4511
4512	my ($type,$qname,$qclass,$qtype,$id,$ip)=split(/\t/);
4513
4514	if(($qtype eq "A" \|\| $qtype eq "ANY") && $qname eq "webserver.example.com") {
4515	print STDERR "$$ Sent A records\n";
4516	print "DATA $qname $qclass A 3600 -1 1.2.3.4\n";
4517	print "DATA $qname $qclass A 3600 -1 1.2.3.5\n";
4518	print "DATA $qname $qclass A 3600 -1 1.2.3.6\n";
4519	}
4520	elsif(($qtype eq "CNAME" \|\| $qtype eq "ANY") && $qname eq "www.example.com") {
4521	print STDERR "$$ Sent CNAME records\n";
4522	print "DATA $qname $qclass CNAME 3600 -1 webserver.example.com\n";
4523	}
4524	elsif($qtype eq "MBOXFW") {
4525	print STDERR "$$ Sent MBOXFW records\n";
4526	print "DATA $qname $qclass MBOXFW 3600 -1 powerdns\@example.com\n";
4527	}
4528
4529
4530	print STDERR "$$ End of data\n";
4531	print "END\n";
4532	}
4533	</screen>
4534	</para>
4535	</sect3>
4536	</sect2>
4537
4538	</sect1>
4539	<sect1 id="mysqlbackend"><Title>MySQL backend</title>
4540	<para>
4541	<table>
4542	<title>MySQL backend capabilities</title>
4543	<tgroup cols=2>
4544	<tbody>
4545	<row><entry>Native</entry><entry>Yes</entry></row>
4546	<row><entry>Master</entry><entry>No</entry></row>
4547	<row><entry>Slave</entry><entry>No</entry></row>
4548	<row><entry>Superslave</entry><entry>No</entry></row>
4549	<row><entry>Autoserial</entry><entry>Yes</entry></row>
4550	<row><entry>Case</entry><entry>Insensitive</entry></row>
4551	</tbody>
4552	</tgroup>
4553	</table>
4554	</para>
4555	<para>
4556	The MySQL Backend as present in PDNS is fixed - it requires a certain database schema to function. This schema corresponds to this create statement:
4557
4558	<screen>
4559	CREATE TABLE records (
4560	id int(11) NOT NULL auto_increment,
4561	domain_id int(11) default NULL,
4562	name varchar(255) default NULL,
4563	type varchar(6) default NULL,
4564	content varchar(255) default NULL,
4565	ttl int(11) default NULL,
4566	prio int(11) default NULL,
4567	change_date int(11) default NULL,
4568	PRIMARY KEY (id),
4569	KEY name_index(name),
4570	KEY nametype_index(name,type),
4571	KEY domainid_index(domain_id)
4572	);
4573	</screen>
4574
4575	Every domain should have a unique domain_id, which should remain identical for all records in a domain. Records with a domain_id that
4576	differs from that in the domain SOA record will not appear in a zone transfer.
4577
4578	</para>
4579	<para>
4580	The change_date may optionally
4581	be updated to the time_t (the number of seconds since midnight UTC at the start of 1970), and is in that case used to auto calculate the
4582	SOA serial number in case that is unspecified.
4583
4584	</para>
4585	<sect2><title>Configuration settings</title>
4586	<para>
4587	WARNING! Make sure that you can actually resolve the hostname of your database without accessing the database! It is advised to supply
4588	an IP address here to prevent chicken/egg problems!
4589	</para>
4590	<para>
4591	<variablelist>
4592	<varlistentry>
4593	<term>mysql-dbname</term>
4594	<listitem>
4595	<para>
4596	Database name to connect to
4597	</para>
4598	</listitem>
4599	</varlistentry>
4600	<varlistentry>
4601	<term>mysql-host</term>
4602	<listitem>
4603	<para>
4604	Database host to connect to
4605	</para>
4606	</listitem>
4607	</varlistentry>
4608	<varlistentry>
4609	<term>mysql-password</term>
4610	<listitem>
4611	<para>
4612	Password to connect with
4613	</para>
4614	</listitem>
4615	</varlistentry>
4616	<varlistentry>
4617	<term>mysql-socket</term>
4618	<listitem>
4619	<para>
4620	MySQL socket to use for connecting
4621	</para>
4622	</listitem>
4623	</varlistentry>
4624	<varlistentry>
4625	<term>mysql-table</term>
4626	<listitem>
4627	<para>
4628	MySQL table name. Defaults to 'records'.
4629	</para>
4630	</listitem>
4631	</varlistentry>
4632	<varlistentry>
4633	<term>mysql-user</term>
4634	<listitem>
4635	<para>
4636	MySQL user to connect as
4637	</para>
4638	</listitem>
4639	</varlistentry>
4640	</variablelist>
4641	</para>
4642	</sect2>
4643	<sect2><title>Notes</title>
4644	<para>
4645	It has been observed that InnoDB tables outperform the default MyISAM tables by a large margin. Furthermore, the default
4646	number of backends (3) should be raised to 10 or 15 for busy servers.
4647	</para>
4648	</sect2>
4649
4650	</sect1>
4651	<sect1 id="pdnsbackend"><Title>MySQL PDNS backend</title>
4652	<para>
4653	<table>
4654	<title>MySQL backend capabilities</title>
4655	<tgroup cols=2>
4656	<tbody>
4657	<row><entry>Native</entry><entry>Yes</entry></row>
4658	<row><entry>Master</entry><entry>No</entry></row>
4659	<row><entry>Slave</entry><entry>No</entry></row>
4660	<row><entry>Superslave</entry><entry>No</entry></row>
4661	<row><entry>Autoserial</entry><entry>Yes</entry></row>
4662	<row><entry>Case</entry><entry>Insensitive</entry></row>
4663	</tbody>
4664	</tgroup>
4665	</table>
4666	</para>
4667	<para>
4668	This is the driver that corresponds to the set of XML-RPC tools available from PowerDNS. For database schemas, see there.
4669	</para>
4670	<para>
4671	It takes a number of parameters:
4672	</para>
4673	<para>
4674	<variablelist>
4675	<varlistentry>
4676	<term>pdns-dbname</term>
4677	<listitem>
4678	<para>
4679	Database name to connect to
4680	</para>
4681	</listitem>
4682	</varlistentry>
4683	<varlistentry>
4684	<term>pdns-host</term>
4685	<listitem>
4686	<para>
4687	Database host to connect to
4688	</para>
4689	</listitem>
4690	</varlistentry>
4691	<varlistentry>
4692	<term>pdns-password</term>
4693	<listitem>
4694	<para>
4695	Password to connect with
4696	</para>
4697	</listitem>
4698	</varlistentry>
4699	<varlistentry>
4700	<term>pdns-socket</term>
4701	<listitem>
4702	<para>
4703	MySQL socket to use for connecting
4704	</para>
4705	</listitem>
4706	</varlistentry>
4707	<varlistentry>
4708	<term>pdns-user</term>
4709	<listitem>
4710	<para>
4711	MySQL user to connect as
4712	</para>
4713	</listitem>
4714	</varlistentry>
4715	</variablelist>
4716	</para>
4717	<sect2><title>Notes</title>
4718	<para>
4719	It has been observed that InnoDB tables outperform the default MyISAM tables by a large margin. Furthermore, the default
4720	number of backends (3) should be raised to 10 or 15 for busy servers.
4721	</para>
4722	</sect2>
4723
4724	</sect1>
4725
4726	<sect1 id="generic-mypgsql-backends"><Title>Generic MySQL and PgSQL backends</title>
4727	<para>
4728	<table>
4729	<title>Generic PgSQL and MySQL backend capabilities</title>
4730	<tgroup cols=2>
4731	<tbody>
4732	<row><entry>Module name</entry><entry>gpgsql / gmysql</entry></row>
4733	<row><entry>Native</entry><entry>Yes - but PostgreSQL does not replicate</entry></row>
4734	<row><entry>Master</entry><entry>Yes</entry></row>
4735	<row><entry>Slave</entry><entry>Yes</entry></row>
4736	<row><entry>Superslave</entry><entry>Yes</entry></row>
4737	<row><entry>Autoserial</entry><entry>Yes</entry></row>
4738	<row><entry>Case</entry><entry>All lower</entry></row>
4739	</tbody>
4740	</tgroup>
4741	</table>
4742	</para>
4743	<para>
4744	PostgreSQL and MySQL backend with easily configurable SQL statements, allowing you to graft PDNS on any PostgreSQL or MySQL database of your choosing.
4745	Because all database schemas will be different, a generic backend is needed to cover all needs.
4746	</para>
4747	<para>
4748	The template queries are expanded using the C function 'snprintf' which implies that substitutions are performed on the basis of %-place holders.
4749	To place a a % in a query which will not be substituted, use %%. Make sure to fill out the search key, often called 'name' in lower case!
4750	</para>
4751	<para>
4752	There are in fact two backends, one for PostgreSQL and one for MySQL but they accept the same settings and use almost exactly the same database schema.
4753	</para>
4754	<sect2><title>MySQL specifics</title>
4755	<para>
4756	<warning>
4757	<para>
4758	As of 2.3, the Generic MySQL backend has not been tested a lot. Use the regular MySQL backend if unsure! Especially 'master' support is
4759	very new.
4760	</para>
4761	</warning>
4762	<warning>
4763	<para>
4764	If using MySQL with 'slave' support enabled in PowerDNS you <emphasis>must</emphasis> run MySQL with a table engine that supports transactions.
4765	</para>
4766	</warning>
4767	</para>
4768	<para>
4769	In practice, great results are achieved with the 'InnoDB' tables. PowerDNS will silently function with non-transaction aware MySQLs but at one point
4770	this is going to harm your database, for example when an incoming zone transfer fails.
4771	</para>
4772	<para>
4773	The default setup conforms to the following schema:
4774	<programlisting>
4775	create table domains (
4776	id INT auto_increment,
4777	name VARCHAR(255) NOT NULL,
4778	master VARCHAR(20) DEFAULT NULL,
4779	last_check INT DEFAULT NULL,
4780	type VARCHAR(6) NOT NULL,
4781	notified_serial INT DEFAULT NULL,
4782	account VARCHAR(40) DEFAULT NULL,
4783	primary key (id)
4784	)type=InnoDB;
4785
4786	CREATE UNIQUE INDEX name_index ON domains(name);
4787
4788	CREATE TABLE records (
4789	id INT auto_increment,
4790	domain_id INT DEFAULT NULL,
4791	name VARCHAR(255) DEFAULT NULL,
4792	type VARCHAR(6) DEFAULT NULL,
4793	content VARCHAR(255) DEFAULT NULL,
4794	ttl INT DEFAULT NULL,
4795	prio INT DEFAULT NULL,
4796	change_date INT DEFAULT NULL,
4797	primary key(id)
4798	)type=InnoDB;
4799
4800	CREATE INDEX rec_name_index ON records(name);
4801	CREATE INDEX nametype_index ON records(name,type);
4802	CREATE INDEX domain_id ON records(domain_id);
4803
4804	create table supermasters (
4805	ip VARCHAR(25) NOT NULL,
4806	nameserver VARCHAR(255) NOT NULL,
4807	account VARCHAR(40) DEFAULT NULL
4808	);
4809
4810	GRANT SELECT ON supermasters TO pdns;
4811	GRANT ALL ON domains TO pdns;
4812	GRANT ALL ON records TO pdns;
4813	</programlisting>
4814	</para>
4815	<para>
4816	This schema contains all elements needed for master, slave and superslave operation. Depending on which features will be used, the 'GRANT' statements
4817	can be trimmed to make sure PDNS cannot subvert the contents of your database.
4818	</para>
4819	<para>
4820	Zone2sql with the --gmysql flag also assumes this layout is in place.
4821	</para>
4822	</sect2>
4823	<sect2><title>PostgresSQL specifics</title>
4824	<para>
4825	The default setup conforms to the following schema:
4826	<programlisting>
4827	create table domains (
4828	id SERIAL PRIMARY KEY,
4829	name VARCHAR(255) NOT NULL,
4830	master VARCHAR(20) DEFAULT NULL,
4831	last_check INT DEFAULT NULL,
4832	type VARCHAR(6) NOT NULL,
4833	notified_serial INT DEFAULT NULL,
4834	account VARCHAR(40) DEFAULT NULL
4835	);
4836	CREATE UNIQUE INDEX name_index ON domains(name);
4837
4838	CREATE TABLE records (
4839	id SERIAL PRIMARY KEY,
4840	domain_id INT DEFAULT NULL,
4841	name VARCHAR(255) DEFAULT NULL,
4842	type VARCHAR(6) DEFAULT NULL,
4843	content VARCHAR(255) DEFAULT NULL,
4844	ttl INT DEFAULT NULL,
4845	prio INT DEFAULT NULL,
4846	change_date INT DEFAULT NULL,
4847	CONSTRAINT domain_exists
4848	FOREIGN KEY(domain_id) REFERENCES domains(id)
4849	ON DELETE CASCADE
4850	);
4851
4852	CREATE INDEX rec_name_index ON records(name);
4853	CREATE INDEX nametype_index ON records(name,type);
4854	CREATE INDEX domain_id ON records(domain_id);
4855
4856	create table supermasters (
4857	ip VARCHAR(25) NOT NULL,
4858	nameserver VARCHAR(255) NOT NULL,
4859	account VARCHAR(40) DEFAULT NULL
4860	);
4861
4862	GRANT SELECT ON supermasters TO pdns;
4863	GRANT ALL ON domains TO pdns;
4864	GRANT ALL ON domains_id_seq TO pdns;
4865	GRANT ALL ON records TO pdns;
4866	GRANT ALL ON records_id_seq TO pdns;
4867	</programlisting>
4868	</para>
4869	<para>
4870	This schema contains all elements needed for master, slave and superslave operation. Depending on which features will be used, the 'GRANT' statements
4871	can be trimmed to make sure PDNS cannot subvert the contents of your database.
4872	</para>
4873	<para>
4874	Zone2sql with the --gpgsql flag also assumes this layout is in place.
4875	</para>
4876	</sect2>
4877	<sect2><title>Basic functionality</title>
4878	<para>
4879	4 queries are needed for regular lookups, 4 for 'fancy records' which are disabled by default and 1 is needed for zone transfers.
4880	</para>
4881	<para>The 4+4 regular queries must return the following 6 fields, in this exact order:
4882	<variablelist>
4883	<varlistentry>
4884	<term>content</term>
4885	<listitem>
4886	<para>
4887	This is the 'right hand side' of a DNS record. For an A record, this is the IP address for example.
4888	</para>
4889	</listitem>
4890	</varlistentry>
4891	<varlistentry>
4892	<term>ttl</term>
4893	<listitem>
4894	<para>
4895	TTL of this record, in seconds. Must be a real value, no checking is performed.
4896	</para>
4897	</listitem>
4898	</varlistentry>
4899	<varlistentry>
4900	<term>prio</term>
4901	<listitem>
4902	<para>
4903	For MX records, this should be the priority of the mail exchanger specified.
4904	</para>
4905	</listitem>
4906	</varlistentry>
4907	<varlistentry>
4908	<term>qtype</term>
4909	<listitem>
4910	<para>
4911	The ASCII representation of the qtype of this record. Examples are 'A', 'MX', 'SOA', 'AAAA'. Make sure that this
4912	field returns an exact answer - PDNS won't recognise 'A ' as 'A'. This can be achieved by using a VARCHAR instead
4913	of a CHAR.
4914	</para>
4915	</listitem>
4916
4917	</varlistentry>
4918	<varlistentry>
4919	<term>domain_id</term>
4920	<listitem>
4921	<para>
4922	Each domain must have a unique domain_id. No two domains may share a domain_id, all records in a domain should have the same. A number.
4923	</para>
4924	</listitem>
4925	</varlistentry>
4926	<varlistentry>
4927	<term>name</term>
4928	<listitem>
4929	<para>
4930	Actual name of a record. Must not end in a '.' and be fully qualified - it is not relative to the name of the domain!
4931	</para>
4932	</listitem>
4933	</varlistentry>
4934	</variablelist>
4935	Please note that the names of the fields are not relevant, but the order is!
4936	</para>
4937	<para>
4938	As said earlier, there are 8 SQL queries for regular lookups. To configure them, set 'gmysql-basic-query' or 'gpgsql-basic-query', depending on your
4939	choice of backend. If so called 'MBOXFW' fancy records are not used, four queries remain:
4940	<variablelist>
4941	<varlistentry>
4942	<term>basic-query</term>
4943	<listitem>
4944	<para>
4945	Default: <command>select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name='%s'</command>
4946	This is the most used query, needed for doing 1:1 lookups of qtype/name values. First %s is replaced by the ASCII representation
4947	of the qtype of the question, the second by the name.
4948	</para>
4949	</listitem>
4950	</varlistentry>
4951	<varlistentry>
4952	<term>id-query</term>
4953	<listitem>
4954	<para>
4955	Default: <command>select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name='%s' and domain_id=%d</command>
4956	Used for doing lookups within a domain. First %s is replaced by the qtype, the %d which should appear after the %s by the numeric
4957	domain_id.
4958	</para>
4959	</listitem>
4960	</varlistentry>
4961
4962	<varlistentry>
4963	<term>any-query</term>
4964	<listitem>
4965	<para>
4966	For doing ANY queries. Also used internally.
4967	Default: <command>select content,ttl,prio,type,domain_id,name from records where name='%s'</command>
4968	The %s is replaced by the qname of the question.
4969	</para>
4970	</listitem>
4971	</varlistentry>
4972	<varlistentry>
4973	<term>any-id-query</term>
4974	<listitem>
4975	<para>
4976	For doing ANY queries within a domain. Also used internally.
4977	Default: <command>select content,ttl,prio,type,domain_id,name from records where name='%s' and domain_id=%d</command>
4978	The %s is replaced by the name of the domain, the %d by the numerical domain id.
4979	</para>
4980	</listitem>
4981	</varlistentry>
4982	</variablelist>
4983	</para>
4984	<para>
4985	The last query is for listing the entire contents of a zone. This is needed when performing a zone transfer, but sometimes also internally:
4986	<variablelist>
4987	<varlistentry>
4988	<term>list-query</term>
4989	<listitem>
4990	<para>
4991	To list an entire zone.
4992	Default: <command>select content,ttl,prio,type,domain_id,name from records where domain_id=%d</command>
4993	</para>
4994	</listitem>
4995	</varlistentry>
4996	</variablelist>
4997	</para>
4998	</sect2>
4999	<sect2><title>Fancy records</title>
5000	<para>
5001	If PDNS is used with so called 'Fancy Records', the 'MBOXFW' record exists which specifies an email address forwarding instruction,
5002	wildcard queries are sometimes needed. This is not enabled by default. A wildcard query is
5003	an internal concept - it has no relation to *.domain-type lookups. You can safely leave these queries blank.
5004	<variablelist>
5005	<varlistentry>
5006	<term>wildcard-query</term>
5007	<listitem>
5008	<para>
5009	Can be left blank. See above for an explanation.
5010	Default: <command>select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name like '%s'</command>
5011	</para>
5012	</listitem>
5013	</varlistentry>
5014	<varlistentry>
5015	<term>wildcard-id-query</term>
5016	<listitem>
5017	<para>
5018	Can be left blank. See above for an explanation.
5019	Default: <command>select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name like '%s' and domain_id=%d</command>
5020	Used for doing lookups within a domain.
5021	</para>
5022	</listitem>
5023	</varlistentry>
5024	<varlistentry>
5025	<term>wildcard-any-query</term>
5026	<listitem>
5027	<para>
5028	For doing wildcard ANY queries.
5029	Default: <command>select content,ttl,prio,type,domain_id,name from records where name like '%s'</command>
5030	</para>
5031	</listitem>
5032	</varlistentry>
5033	<varlistentry>
5034	<term>wildcard-any-id-query</term>
5035	<listitem>
5036	<para>
5037	For doing wildcard ANY queries within a domain.
5038	Default: <command>select content,ttl,prio,type,domain_id,name from records where name like '%s' and domain_id=%d</command>
5039	</para>
5040	</listitem>
5041	</varlistentry>
5042	</variablelist>
5043	</para>
5044	</sect2>
5045
5046	<sect2><title>Settings and specifying queries</title>
5047	<para>
5048	The queries above are specified in pdns.conf. For example, the basic-query would appear as:
5049	<screen>
5050	gpgsql-basic-query=select content,ttl,prio,type,domain_id,name from records where qtype='%s' and name='%s'
5051	</screen>
5052
5053	Queries can span multiple lines, like this:
5054	<screen>
5055	gpgsql-basic-query=select content,ttl,prio,type,domain_id,name from records \
5056	where qtype='%s' and name='%s'
5057	</screen>
5058	Do not wrap statements in quotes as this will not work.
5059	Besides the query related settings, the following configuration options are available:
5060	</para>
5061	<para>
5062	<variablelist>
5063	<varlistentry>
5064	<term>gpgsql-dbname</term>
5065	<listitem>
5066	<para>
5067	Database name to connect to
5068	</para>
5069	</listitem>
5070	</varlistentry>
5071	<varlistentry>
5072	<term>gpgsql-host</term>
5073	<listitem>
5074	<para>
5075	Database host to connect to. WARNING: When specified as a hostname a chicken/egg situation might arise where the database
5076	is needed to resolve the IP address of the database. It is best to supply an IP address of the database here.
5077	</para>
5078	</listitem>
5079	</varlistentry>
5080	<varlistentry>
5081	<term>gpgsql-password</term>
5082	<listitem>
5083	<para>
5084	Password to connect with
5085	</para>
5086	</listitem>
5087	</varlistentry>
5088	<varlistentry>
5089	<term>gpgsql-user</term>
5090	<listitem>
5091	<para>
5092	PgSQL user to connect as
5093	</para>
5094	</listitem>
5095	</varlistentry>
5096	</variablelist>
5097	</para>
5098	</sect2>
5099	<sect2><title>Native operation</title>
5100	<para>
5101	For native operation, either drop the FOREIGN KEY on the domain_id field, or (recommended), make sure
5102	the <command>domains</command> table is filled properly. To add a domain, issue the following:
5103	<programlisting>
5104	insert into domains (name,type) values ('powerdns.com','NATIVE');
5105	</programlisting>
5106	The records table can now be filled by with the domain_id set to the id of the domains table row just inserted.
5107	</para>
5108	</sect2>
5109	<sect2><title>Slave operation</title>
5110	<para>
5111	The PostgreSQL backend is fully slave capable. To become a slave of the 'powerdns.com' domain, execute this:
5112	<programlisting>
5113	insert into domains (name,master,type) values ('powerdns.com','213.244.168.217','SLAVE');
5114	</programlisting>
5115	And wait a while for PDNS to pick up the addition - which happens within one minute. There is no need to inform PDNS that a new domain
5116	was added.
5117	Typical output is:
5118	<programlisting>
5119	Apr 09 13:34:29 All slave domains are fresh
5120	Apr 09 13:35:29 1 slave domain needs checking
5121	Apr 09 13:35:29 Domain powerdns.com is stale, master serial 1, our serial 0
5122	Apr 09 13:35:30 [gPgSQLBackend] Connected to database
5123	Apr 09 13:35:30 AXFR started for 'powerdns.com'
5124	Apr 09 13:35:30 AXFR done for 'powerdns.com'
5125	Apr 09 13:35:30 [gPgSQLBackend] Closing connection
5126	</programlisting>
5127	</para>
5128	<para>
5129	From now on, PDNS is authoritative for the 'powerdns.com' zone and will respond accordingly for queries within that zone.
5130	</para>
5131	<para>
5132	Periodically, PDNS schedules checks to see if domains are still fresh. The default <command>slave-cycle-interval</command> is 60 seconds, large installations may need to raise this value. Once a domain has been checked, it will not be checked before its SOA refresh timer has expired. Domains whose status is unknown get checked every 60 seconds by default.
5133	</para>
5134	</sect2>
5135	<sect2><title>Superslave operation</title>
5136	<para>
5137	To configure a supermaster with IP address 10.0.0.11 which lists this installation as 'autoslave.powerdns.com', issue the following:
5138	<programlisting>
5139	insert into supermasters ('10.0.0.11','autoslave.powerdns.com','internal');
5140	</programlisting>
5141	From now on, valid notifies from 10.0.0.11 that list a NS record containing 'autoslave.powerdns.com' will lead to the
5142	provisioning of a slave domain under the account 'internal'. See <xref linkend="supermaster"> for details.
5143	</para>
5144	</sect2>
5145	<sect2><title>Master operation</title>
5146	<para>
5147	The PostgreSQL backend is fully master capable with automatic discovery of serial changes. Raising the serial number of a domain
5148	suffices to trigger PDNS to send out notifications. To configure a domain for master operation instead of the default native replication,
5149	issue:
5150	<programlisting>
5151	insert into domains (name,type) values ('powerdns.com','MASTER');
5152	</programlisting>
5153	Make sure that the assigned id in the domains table matches the domain_id field in the records table!
5154	</para>
5155	</sect1>
5156
5157	<sect1 id="oracle"><Title>Generic Oracle backend</title>
5158	<para>
5159	<table>
5160	<title>Oracle backend capabilities</title>
5161	<tgroup cols=2>
5162	<tbody>
5163	<row><entry>Native</entry><entry>Yes</entry></row>
5164	<row><entry>Master</entry><entry>No</entry></row>
5165	<row><entry>Slave</entry><entry>No</entry></row>
5166	<row><entry>Superslave</entry><entry>No</entry></row>
5167	<row><entry>Autoserial</entry><entry>Yes</entry></row>
5168	</tbody>
5169	</tgroup>
5170	</table>
5171	</para>
5172	<para>
5173	Oracle backend with easily configurable SQL statements, allowing you to graft PDNS on any Oracle database of your choosing.
5174	</para>
5175	<para>
5176	PowerDNS is currently ascertaining if this backend can be distributed in binary form without violating Oracle licensing. In the meantime,
5177	the source code to the Oracle backend is available for runtime linking into dynamic versions of PowerDNS. See
5178	<ulink url="http://downloads.powerdns.com/backends">http://downloads.powerdns.com/backends</ulink> for sources.
5179	</para>
5180	<para>
5181	The following configuration settings are available:
5182	</para>
5183	<para>
5184	<variablelist>
5185	<varlistentry>
5186	<term>oracle-debug-queries</term>
5187	<listitem>
5188	<para>
5189	Output all queries to disk for debugging purposes.
5190	</para>
5191	</listitem>
5192	</varlistentry>
5193	<varlistentry>
5194	<term>oracle-time-queries</term>
5195	<listitem>
5196	<para>
5197	Output all queries to disk for timing purposes.
5198	</para>
5199	</listitem>
5200	</varlistentry>
5201	<varlistentry>
5202	<term>oracle-uppercase-database</term>
5203	<listitem>
5204	<para>
5205	Change all domain names to uppercase before querying database.
5206	</para>
5207	</listitem>
5208	</varlistentry>
5209	<varlistentry>
5210	<term>oracle-database</term>
5211	<listitem>
5212	<para>
5213	Oracle database name to connect to.
5214	</para>
5215	</listitem>
5216	</varlistentry>
5217	<varlistentry>
5218	<term>oracle-home</term>
5219	<listitem>
5220	<para>
5221	PDNS can set the ORACLE_HOME environment variable from within the executable, allowing execution of
5222	the daemon from init.d scripts where ORACLE_HOME may not yet be set.
5223	</para>
5224	</listitem>
5225	</varlistentry>
5226	<varlistentry>
5227	<term>oracle-sid</term>
5228	<listitem>
5229	<para>
5230	PDNS can set the ORACLE_SID environment variable from within the executable, allowing execution of
5231	the daemon from init.d scripts where ORACLE_SID may not yet be set.
5232	</para>
5233	</listitem>
5234	</varlistentry>
5235	<varlistentry>
5236	<term>oracle-username</term>
5237	<listitem>
5238	<para>
5239	Oracle username to connect as.
5240	</para>
5241	</listitem>
5242	</varlistentry>
5243	<varlistentry>
5244	<term>oracle-password</term>
5245	<listitem>
5246	<para>
5247	Oracle password to connect with.
5248	</para>
5249	</listitem>
5250	</varlistentry>
5251	</variablelist>
5252	</para>
5253	<para>
5254	The generic Oracle backend can be configured to use user-specified queries. The following are the default queries
5255	and their names:
5256	</para>
5257	<para>
5258	<variablelist>
5259	<varlistentry>
5260	<term>oracle-forward-query</term>
5261	<listitem>
5262	<para>
5263	select content, TimeToLive, Priority, type, ZoneId, nvl(ChangeDate,0) from Records where name = :name and type = :type
5264	</para>
5265	</listitem>
5266	</varlistentry>
5267	<varlistentry>
5268	<term>oracle-forward-query-by-zone</term>
5269	<listitem>
5270	<para>
5271	select content, TimeToLive, Priority, type, ZoneId, nvl(ChangeDate,0) from records where name = :name and type = :type and ZoneId = :id
5272	</para>
5273	</listitem>
5274	</varlistentry>
5275	<varlistentry>
5276	<term>oracle-forward-any-query</term>
5277	<listitem>
5278	<para>
5279	select content, TimeToLive, Priority, type, ZoneId, nvl(ChangeDate,0) from records where name = :name
5280	</para>
5281	</listitem>
5282	</varlistentry>
5283	<varlistentry>
5284	<term>oracle-list-query</term>
5285	<listitem>
5286	<para>
5287	select content, TimeToLive, Priority, type, ZoneId, nvl(ChangeDate, 0), name from records where ZoneId = :id
5288	</para>
5289	</listitem>
5290	</varlistentry>
5291	</variablelist>
5292	</para>
5293	<sect2><title>Setting up Oracle for use with PowerDNS</title>
5294	<para>
5295	To setup a database that corresponds to these default queries, issue the following as Oracle user sys:
5296	<screen>
5297	create user powerdns identified by YOURPASSWORD;
5298	grant connect to powerdns;
5299
5300	create tablespace powerdns datafile '/opt/oracle/oradata/oracle/powerdns.dbf'
5301	size 256M extent management local autoallocate;
5302
5303	alter user powerdns quota unlimited on powerdns;
5304	</screen>
5305	</para>
5306	<para>
5307	As user 'powerdns' continue with:
5308	<screen>
5309	create table Domains (
5310	ID number(11) NOT NULL,
5311	NAME VARCHAR(255) NOT NULL,
5312	MASTER VARCHAR(20) DEFAULT NULL,
5313	LAST_CHECK INT DEFAULT NULL,
5314	TYPE VARCHAR(6) NOT NULL,
5315	NOTIFIED_SERIAL INT DEFAULT NULL,
5316	ACCOUNT VARCHAR(40) DEFAULT NULL,
5317	primary key (ID)
5318	)tablespace POWERDNS;
5319
5320	create index DOMAINS$NAME on Domains (NAME) tablespace POWERDNS;
5321	create sequence DOMAINS_ID_SEQUENCE;
5322
5323	create table Records
5324	(
5325	ID number(11) NOT NULL,
5326	ZoneID number(11) default NULL REFERENCES Domains(ID) ON DELETE CASCADE,
5327	NAME varchar2(255) default NULL,
5328	TYPE varchar2(6) default NULL,
5329	CONTENT varchar2(255) default NULL,
5330	TimeToLive number(11) default NULL,
5331	Priority number(11) default NULL,
5332	CreateDate number(11) default NULL,
5333	ChangeDate number(11) default NULL,
5334	primary key (ID)
5335	)tablespace POWERDNS;
5336
5337	create index RECORDS$NAME on RECORDS (NAME) tablespace POWERDNS;
5338	create sequence RECORDS_ID_SEQUENCE;
5339	</screen>
5340	</para>
5341	<para>
5342	To insert records, either use <command>zone2sql</command> with the <command>--oracle</command> setting, or execute sql
5343	along the lines of:
5344	<screen>
5345	insert into domains (id,name,type) values (domains_id_sequence.nextval,'netherlabs.nl','NATIVE');
5346	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';
5347	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';
5348	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';
5349	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';
5350	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';
5351	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';
5352
5353	</screen>
5354	</para>
5355	<para>
5356	For performance reasons it is best to specify <command>--transactions</command> too!
5357	</para>
5358	</sect2>
5359	</sect1>
5360
5361	<sect1 id="db2"><Title>DB2 backend</title>
5362	<para>
5363	<table>
5364	<title>DB2 backend capabilities</title>
5365	<tgroup cols=2>
5366	<tbody>
5367	<row><entry>Native</entry><entry>Yes</entry></row>
5368	<row><entry>Master</entry><entry>No</entry></row>
5369	<row><entry>Slave</entry><entry>No</entry></row>
5370	<row><entry>Superslave</entry><entry>No</entry></row>
5371	<row><entry>Autoserial</entry><entry>Yes</entry></row>
5372	</tbody>
5373	</tgroup>
5374	</table>
5375	</para>
5376	<para>
5377	PowerDNS is currently ascertaining if this backend can be distributed in binary form without violating IBM DB2 licensing. If you have a DB2 license,
5378	please contact pdns@powerdns.com so we can ship you a copy of this driver.
5379	</para>
5380	<para>
5381	The DB2 backend executes the following queries:
5382	<variablelist>
5383	<varlistentry>
5384	<term>Forward Query</term>
5385	<listitem>
5386	<para>
5387	select Content, TimeToLive, Priority, Type, ZoneId, 0 as ChangeDate, Name from Records where Name = ? and type = ?
5388	</para>
5389	</listitem>
5390	</varlistentry>
5391	<varlistentry>
5392	<term>Forward By Zone Query</term>
5393	<listitem>
5394	<para>
5395	select Content, TimeToLive, Priority, Type, ZoneId, 0 as ChangeDate, Name from Records where Name = ? and Type = ? and ZoneId = ?
5396	</para>
5397	</listitem>
5398	</varlistentry>
5399	<varlistentry>
5400	<term>Forward Any Query</term>
5401	<listitem>
5402	<para>
5403	select Content, TimeToLive, Priority, Type, ZoneId, 0 as ChangeDate, Name from Records where Name = ?
5404	</para>
5405	</listitem>
5406	</varlistentry>
5407	<varlistentry>
5408	<term>List Query</term>
5409	<listitem>
5410	<para>
5411	select Content, TimeToLive, Priority, Type, ZoneId, 0 as ChangeDate, Name from Records where ZoneId = ?
5412	</para>
5413	</listitem>
5414	</varlistentry>
5415	</variablelist>
5416	</para>
5417	<para>
5418	Configuration settings:
5419	<variablelist>
5420	<varlistentry>
5421	<term>db2-server</term>
5422	<listitem>
5423	<para>
5424	Server name to connect to. Defaults to 'powerdns'. Make sure that your nameserver is not needed to resolve an IP address needed to connect as
5425	this might lead to a chicken/egg situation.
5426	</para>
5427	</listitem>
5428	</varlistentry>
5429	<varlistentry>
5430	<term>db2-user</term>
5431	<listitem>
5432	<para>
5433	Username to connect as. Defaults to 'powerdns'.
5434	</para>
5435	</listitem>
5436	</varlistentry>
5437	<varlistentry>
5438	<term>db2-password</term>
5439	<listitem>
5440	<para>
5441	Password to connect with. Defaults to 'powerdns'.
5442	</para>
5443	</listitem>
5444	</varlistentry>
5445	</variablelist>
5446	</para>
5447	</sect1>
5448
5449	<sect1 id="bindbackend"><Title>Bind zone file backend</title>
5450	<para>
5451	<table>
5452	<title>Bind zone file backend capabilities</title>
5453	<tgroup cols=2>
5454	<tbody>
5455	<row><entry>Native</entry><entry>Yes</entry></row>
5456	<row><entry>Master</entry><entry>No</entry></row>
5457	<row><entry>Slave</entry><entry>Experimental</entry></row>
5458	<row><entry>Superslave</entry><entry>No</entry></row>
5459	<row><entry>Autoserial</entry><entry>No</entry></row>
5460	</tbody>
5461	</tgroup>
5462	</table>
5463	</para>
5464	<para>
5465	The BindBackend started life as a demonstration of the versatility of PDNS but quickly gained in importance when there appeared to be demand
5466	for a Bind 'workalike'.
5467	</para>
5468	<para>
5469	The BindBackend parses a Bind-style named.conf and extracts information about zones from it. It makes no attempt to honour other configuration flags,
5470	which you should configure (when available) using the PDNS native configuration.
5471	</para>
5472	<para>
5473	<variablelist>
5474	<varlistentry>
5475	<term>--help=bind</term>
5476	<listitem>
5477	<para>
5478	Outputs all known parameters related to the bindbackend
5479	</para>
5480	</listitem>
5481	</varlistentry>
5482	<varlistentry>
5483	<term>bind-example-zones</term>
5484	<listitem>
5485	<para>
5486	Loads the 'example.com' zone which can be queried to determine if PowerDNS is functioning without configuring
5487	database backends.
5488	</para>
5489	</listitem>
5490	</varlistentry>
5491	<varlistentry>
5492	<term>bind-config=</term>
5493	<listitem>
5494	<para>
5495	Location of the Bind configuration file to parse.
5496	</para>
5497	</listitem>
5498	</varlistentry>
5499	<varlistentry>
5500	<term>bind-check-interval=</term>
5501	<listitem>
5502	<para>
5503	How often to check for zone changes. See 'Operation' section.
5504	</para>
5505	</listitem>
5506	</varlistentry>
5507	<varlistentry>
5508	<term>bind-enable-huffman</term>
5509	<listitem>
5510	<para>
5511	Enable Huffman compression on zone data. Currently saves around 20% of memory actually used, but slows down operation
5512	somewhat.
5513	</para>
5514	</listitem>
5515	</varlistentry>
5516	</variablelist>
5517	</para>
5518	<sect2>
5519	<title>Operation</title>
5520	<para>
5521	On launch, the BindBackend first parses the named.conf to determine which zones need to be loaded. These will then be parsed
5522	and made available for serving, as they are parsed. So a named.conf with 100.000 zones may take 20 seconds to load, but after 10 seconds,
5523	50.000 zones will already be available. While a domain is being loaded, it is not yet available, to prevent incomplete answers.
5524	</para>
5525	<para>
5526	Reloading is currently done only when a request for a zone comes in, and then only after <command>bind-check-interval</command> seconds have passed
5527	after the last check. If a change occurred, access to the zone is disabled, the file is reloaded, access is restored, and the question is answered.
5528	For regular zones, reloading is fast enough to answer the question which lead to the reload within the DNS timeout.
5529	</para>
5530	<para>
5531	If <command>bind-check-interval</command> is specified as zero, no checks will be performed.
5532	</para>
5533	<sect2><title>Performance</title>
5534	<para>
5535	The BindBackend does not benefit from the packet cache as it is fast enough on its own. Furthermore, on most systems, there will
5536	be no benefit in using multiple CPUs for the packetcache, so a noticeable speedup can be attained by specifying
5537	<command>distributor-threads=1</command> in <filename>pdns.conf</filename>.
5538	</para>
5539	</sect2>
5540	<sect2><title>Master/slave configuration</title>
5541	<para>
5542	Currently disabled in prereleases. But see <xref linkend="slave">.
5543	</para>
5544	</sect2>
5545	</sect1>
5546
5547	<sect1 id="odbc">
5548	<Title>ODBC backend</Title>
5549	<para>
5550	<table>
5551	<title>ODBC backend capabilities</title>
5552	<tgroup cols=2>
5553	<tbody>
5554	<row><entry>Native</entry><entry>Yes</entry></row>
5555	<row><entry>Master</entry><entry>Yes (experimental)</entry></row>
5556	<row><entry>Slave</entry><entry>Yes (experimental)</entry></row>
5557	<row><entry>Superslave</entry><entry>No</entry></row>
5558	<row><entry>Autoserial</entry><entry>Yes</entry></row>
5559	</tbody>
5560	</tgroup>
5561	</table>
5562	</para>
5563	<para>
5564	The ODBC backend can retrieve zone information from any source that has a ODBC driver available.
5565	<note><para>This backend is only available on PowerDNS for Windows.</para></note>
5566	</para>
5567
5568	<para>
5569	The ODBC backend needs data in a fixed schema which is the same as the data needed by the MySQL backend. The create statement
5570	will resemble this:
5571	<screen>
5572	CREATE TABLE records (
5573	id int(11) NOT NULL auto_increment,
5574	domain_id int(11) default NULL,
5575	name varchar(255) default NULL,
5576	type varchar(6) default NULL,
5577	content varchar(255) default NULL,
5578	ttl int(11) default NULL,
5579	prio int(11) default NULL,
5580	change_date int(11) default NULL,
5581	PRIMARY KEY (id),
5582	KEY name_index(name),
5583	KEY nametype_index(name,type),
5584	KEY domainid_index(domain_id)
5585	);
5586	</screen>
5587	</para>
5588
5589	<para>
5590	To use the ODBC backend an ODBC source has to be created, to do this see the section Installing PowerDNS on Microsoft Windows, <xref linkend="windows">.
5591	</para>
5592
5593	<para>
5594	The following configuration settings are available:
5595
5596	<variablelist>
5597	<varlistentry>
5598	<term>odbc-datasource</term>
5599	<listitem>
5600	<para>
5601	Specifies the name of the data source to use.
5602	</para>
5603	</listitem>
5604	</varlistentry>
5605	<varlistentry>
5606	<term>odbc-user</term>
5607	<listitem>
5608	<para>
5609	Specifies the username that has to be used to log into the datasource.
5610	</para>
5611	</listitem>
5612	</varlistentry>
5613	<varlistentry>
5614	<term>odbc-pass</term>
5615	<listitem>
5616	<para>
5617	Specifies the user's password.
5618	</para>
5619	</listitem>
5620	</varlistentry>
5621	<varlistentry>
5622	<term>odbc-table</term>
5623	<listitem>
5624	<para>
5625	Specifies the name of the table containing the zone information.
5626	</para>
5627	</listitem>
5628	</varlistentry>
5629	</variablelist>
5630	</para>
5631	<para>
5632	The ODBC backend has been tested with Microsoft Access, MySQL (via MyODBC) and Microsoft SQLServer. As the SQL statements used are very basic,
5633	it is expected to work with many ODBC drivers.
5634	</para>
5635	</sect1>
5636
5637	</appendix>
5638	<appendix id="pdns-internals"><title>PDNS internals</title>
5639	<para>
5640	PDNS is normally launched by the init.d script but is actually a binary called <filename>pdns_server</filename>. This
5641	file is started by the <command>start</command> and <command>monitor</command> commands to the init.d script. Other commands
5642	are implemented using the controlsocket.
5643	</para>
5644	<sect1 id="controlsocket"><title>Controlsocket</title>
5645	<para>
5646	The controlsocket is the means to contact a running PDNS daemon, or as we now know, a running <filename>pdns_server</filename>.
5647	Over this sockets, instructions can be sent using the <filename>pdns_control</filename> program. Like the <filename>pdns_server</filename>,
5648	this program is normally accessed via the init.d script.
5649	</para>
5650	<sect2 id="pdnscontrol"><title>pdns_control</title>
5651
5652	<para>
5653	To communicate with PDNS over the controlsocket, the <command>pdns_control</command> command is used. The init.d script also calls
5654	pdns_control. The syntax is simple: <command>pdns_control command arguments</command>. Currently this is most useful for telling backends
5655	to rediscover domains or to force the transmission of notifications. See <xref linkend="master">.
5656	</para>
5657	<para>
5658	Besides the commands implemented by the init.d script, for which see <xref linkend="pdns-on-unix">, the following pdns_control commands
5659	are available:
5660	<variablelist>
5661	<varlistentry>
5662	<term>ccounts</term>
5663	<listitem>
5664	<para>
5665	Returns counts on the contents of the cache.
5666	</para>
5667	</listitem>
5668	</varlistentry>
5669	<varlistentry>
5670	<term>version</term>
5671	<listitem>
5672	<para>
5673	returns the version of a running pdns daemon.
5674	</para>
5675	</listitem>
5676	</varlistentry>
5677	<varlistentry>
5678	<term>purge</term>
5679	<listitem>
5680	<para>
5681	Purges the entire Packet Cache - see <xref linkend="performance">.
5682	</para>
5683	</listitem>
5684	</varlistentry>
5685	<varlistentry>
5686	<term>purge <userinput>record</userinput></term>
5687	<listitem>
5688	<para>
5689	Purges all entries for this exact record name - see <xref linkend="performance">.
5690	</para>
5691	</listitem>
5692	</varlistentry>
5693	<varlistentry>
5694	<term>purge <userinput>record</userinput>$</term>
5695	<listitem>
5696	<para>
5697	Purges all entries ending on this name, effectively purging an entire domain - see <xref linkend="performance">.
5698	</para>
5699	</listitem>
5700	</varlistentry>
5701	<varlistentry>
5702	<term>set <userinput>variable value</userinput></term>
5703	<listitem>
5704	<para>
5705	Set a configuration parameter. Currently only the 'query-logging' parameter can be set.
5706	</para>
5707	</listitem>
5708	</varlistentry>
5709	</variablelist>
5710	</para>
5711	</sect2>
5712	</sect1>
5713
5714	<sect1 id="guardian"><title>Guardian</title>
5715	<para>
5716	When launched by the init.d script, <filename>pdns_server</filename> wraps itself inside a 'guardian'. This guardian monitors the
5717	performance of the inner <filename>pdns_server</filename> instance which shows up in the process list of your OS as
5718	<filename>pdns_server-instance</filename>.
5719
5720	It is also this guardian that <filename>pdns_control</filename> talks to. A <command>STOP</command> is interpreted by the guardian,
5721	which causes the guardian to sever the connection to the inner process and terminate it, after which it terminates itself.
5722
5723	The init.d script <command>DUMP</command> and <command>SHOW</command> commands need to access the inner process, because
5724	the guardian itself does not run a nameserver. For this purpose, the guardian passes controlsocket requests to the control console of the
5725	inner process. This is the same console as seen with init.d <command>MONITOR</command>.
5726	</para></sect1>
5727	<sect1 id="modules"><title>Modules & Backends</title>
5728	<para>
5729	PDNS has the concept of backends and modules. Non-static PDNS distributions have the ability to load new modules at runtime, while the
5730	static versions come with a number of modules built in, but cannot load more.
5731	</para>
5732	<para>
5733	Related parameters are:
5734	<variablelist>
5735	<varlistentry>
5736	<term>--help</term>
5737	<listitem>
5738	<para>
5739	Outputs all known parameters, including those of launched backends, see below.
5740	</para>
5741	</listitem>
5742	</varlistentry>
5743	<varlistentry>
5744	<term>--launch=backend,backend1,backend1:name</term>
5745	<listitem>
5746	<para>
5747	Launches backends. In its most simple form, supply all backends that need to be launched. If you find
5748	that you need to launch single backends multiple times, you can specify a name for later instantiations.
5749	In this case, there are 2 instances of backend1, and the second one is called 'name'.
5750
5751	This means that <command>--backend1-setting</command> is available to configure the first or main instance, and
5752	<command>--backend1-name-setting</command> for the second one.
5753	</para>
5754	</listitem>
5755	</varlistentry>
5756	<varlistentry>
5757	<term>--load-modules=/directory/libyourbackend.so</term>
5758	<listitem>
5759	<para>
5760	If backends are available in nonstandard directories, specify their location here. Multiple files
5761	can be loaded if separated by commas. Only available in non-static PDNS distributions.
5762	</para>
5763	</listitem>
5764	</varlistentry>
5765	<varlistentry>
5766	<term>--list-modules</term>
5767	<listitem>
5768	<para>
5769	Will list all available modules, both compiled in and in dynamically loadable modules.
5770	</para>
5771	</listitem>
5772	</varlistentry>
5773	</variablelist>
5774	To run on the commandline, use the <command>pdns_server</command> binary. For example, to see options for the gpgsql backend,
5775	use the following:
5776	<screen>
5777	$ /usr/sbin/pdns_server --launch=gpgsql --help=gpgsql
5778	</screen>
5779	</para>
5780	</sect1>
5781	<sect1 id="dns-to-query"><title>How PDNS translates DNS queries into backend queries</title>
5782	<para>
5783	A DNS query is not a straightforward lookup. Many DNS queries need to check the backend for additional data, for example to
5784	determine of an unfound record should lead to an NXDOMAIN ('we know about this domain, but that record does not exist') or an
5785	unauthoritative response.
5786	</para>
5787	<para>
5788	Simplified, without CNAME processing and wildcards, the algorithm is like this:
5789	</para>
5790	<para>
5791	When a query for a <command>qname</command>/<command>qtype</command> tuple comes in, it is requested directly from the backend.
5792	If present, PDNS adds the contents of the reply to the list of records to return. A question tuple may generate multiple answer
5793	records.
5794	</para>
5795	<para>
5796	Each of these records is now investigated to see if it needs 'additional processing'. This holds for example for MX records which may
5797	point to hosts for which the PDNS backends also contain data. This involves further lookups for A or AAAA records.
5798	</para>
5799	<para>
5800	After all additional processing has been performed, PDNS sieves out all double records which may well have appeared. The resulting set of
5801	records is added to the answer packet, and sent out.
5802	</para>
5803	<para>
5804	A zone transfer works by looking up the <command>domain_id</command> of the SOA record of the name and then listing all records of that
5805	<command>domain_id</command>. This is why all records in a domain need to have the same domain_id.
5806	</para>
5807	<para>
5808	When a query comes in for an unknown domain, PDNS starts looking for SOA records of all subdomains of the qname, so
5809	no.such.powerdns.com turns into a SOA query for no.such.powerdns.com, such.powerdns.com, powerdns.com, com, ''. When a SOA is found,
5810	that zone is consulted for relevant NS instructions which lead to a referral. If nothing is found within the zone, an authoritative
5811	NXDOMAIN is sent out.
5812	</para>
5813	<para>
5814	If no SOA was found, an unauthoritative no-error is returned.
5815	</para>
5816	<para>
5817	In reality, each query for a question tuple first involves checking for a CNAME, unless that resolution has been disabled with the
5818	<command>skip-cname</command> option.
5819	</para>
5820	<para>
5821	PDNS breaks strict RFC compatability by not always checking for the presence of a SOA record first. This is unlikely to lead to
5822	problems though.
5823	</para>
5824	</appendix>
5825	<appendix id="backend-writers-guide"><title>Backend writers' guide</title>
5826	<para>
5827	PDNS backends are implemented via a simple yet powerful C++ interface. If your needs are not met by the PipeBackend, you
5828	may want to write your own. Doing so requires a copy of the PowerDNS Open Source Backend Development kit which can be found on <ulink
5829	url="http://downloads.powerdns.com/releases/dev">http://downloads.powerdns.com/releases/dev</ulink>.
5830	</para>
5831	<para>
5832	A backend contains zero DNS logic. It need not look for CNAMES, it need not return NS records unless explicitly asked for, etcetera.
5833	All DNS logic is contained within PDNS itself - backends should simply return records matching the description asked for.
5834	</para>
5835	<para>
5836	<warning><para>
5837	However, please note that your backend can get queries in aNy CAsE! If your database is case sensitive, like most are (with the notable
5838	exception of MySQL), you must make sure that you do find answers which differ only in case.
5839	</para></warning>
5840	</para>
5841	<sect1 id="simple-backends"><title>Simple read-only native backends</title>
5842	<para>
5843	Implementing a backend consists of inheriting from the DNSBackend class. For read-only backends, which do not support slave operation,
5844	only the following methods are relevant:
5845
5846	<programlisting>
5847	class DNSBackend
5848	{
5849	public:
5850
5851	virtual bool lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt_p=0, int zoneId=-1)=0;
5852	virtual bool list(int domain_id)=0;
5853	virtual bool get(DNSResourceRecord &r)=0;
5854	virtual bool getSOA(const string &name, SOAData &soadata);
5855	};
5856	</programlisting>
5857
5858	Note that the first three methods must be implemented. <function>getSOA()</function> has a useful default implementation.
5859	</para>
5860	<para>
5861	The semantics are simple. Each instance of your class only handles one (1) query at a time. There is no need for locking as PDNS guarantees
5862	that your backend will never be called reentrantly.
5863	</para>
5864	<para>
5865	Some examples, a more formal specification is down below. A normal lookup starts like this:
5866
5867	<programlisting>
5868	YourBackend yb;
5869	yb.lookup(QType::CNAME,"www.powerdns.com");
5870	</programlisting>
5871
5872	Your class should now do everything to start this query. Perform as much preparation as possible - handling errors at this stage is better for PDNS
5873	than doing so later on. A real error should be reported by throwing an exception.
5874	</para>
5875	<para>
5876	PDNS will then call the <function>get()</function> method to get <command>DNSResourceRecord</command>s back. The following code illustrates
5877	a typical query:
5878
5879	<programlisting>
5880	yb.lookup(QType::CNAME,"www.powerdns.com");
5881
5882	DNSResourceRecord rr;
5883	while(yb.get(rr))
5884	cout<<"Found cname pointing to '"+rr.content+"'"<<endl;
5885	}
5886	</programlisting>
5887	</para>
5888	<para>
5889	Each zone starts with a Start of Authority (SOA) record. This record is special so many backends will choose to implement it
5890	specially. The default <function>getSOA()</function> method performs a regular lookup on your backend to figure out the SOA,
5891	so if you have no special treatment for SOA records, where is no need to implement your own <function>getSOA()</function>.
5892	</para>
5893	<para>
5894	Besides direct queries, PDNS also needs to be able to list a zone, to do zone transfers for example. Each zone has an id which should be
5895	unique within the backend. To list all records belonging to a zone id, the <function>list()</function> method is used. Conveniently,
5896	the domain_id is also available in the <command>SOAData</command> structure.
5897	</para>
5898	<para>
5899	The following lists the contents of a zone called "powerdns.com".
5900
5901	<programlisting>
5902	SOAData sd;
5903	if(!yb.getSOA("powerdns.com",sd)) // are we authoritative over powerdns.com?
5904	return RCode::NotAuth; // no
5905
5906	yb.list(sd.domain_id);
5907	while(yb.get(rr))
5908	cout<<rr.qname<<"\t IN "<<rr.qtype.getName()<<"\t"<<rr.content<<endl;
5909	</programlisting>
5910	</para>
5911	<para>
5912	Please note that when so called 'fancy records' (see <xref linkend="fancy-records">) are enabled, a backend can receive
5913	wildcard lookups. These have a % as the first character of the qdomain in lookup.
5914	</para>
5915	<sect2><title>A sample minimal backend</title>
5916	<para>
5917	This backend only knows about the host "random.powerdns.com", and furthermore, only about its A record:
5918
5919	<programlisting>
5920	/* FIRST PART */
5921	class RandomBackend : public DNSBackend
5922	{
5923	public:
5924	bool list(int id) {
5925	return false; // we don't support AXFR
5926	}
5927
5928	void lookup(const QType &type, const string &qdomain, DNSPacket *p, int zoneId)
5929	{
5930	if(type.getCode()!=QType::A \|\| qdomain!="random.powerdns.com") // we only know about random.powerdns.com A
5931	d_answer=""; // no answer
5932	else {
5933	ostringstream os;
5934	os<<random()%256<<"."<<random()%256<<"."<<random()%256<<"."<<random()%256;
5935	d_answer=os.str(); // our random ip address
5936	}
5937	}
5938
5939	bool get(DNSResourceRecord &rr)
5940	{
5941	if(!d_answer.empty()) {
5942	rr.qname="random.powerdns.com"; // fill in details
5943	rr.qtype=QType::A; // A record
5944	rr.ttl=86400; // 1 day
5945	rr.content=d_answer;
5946
5947	d_answer=""; // this was the last answer
5948
5949	return true;
5950	}
5951	return false; // no more data
5952	}
5953
5954	private:
5955	string d_answer;
5956	};
5957
5958	/* SECOND PART */
5959
5960	class RandomFactory : public BackendFactory
5961	{
5962	public:
5963	RandomFactory() : BackendFactory("random") {}
5964
5965	DNSBackend *make(const string &suffix)
5966	{
5967	return new RandomBackend();
5968	}
5969	};
5970
5971	/* THIRD PART */
5972
5973	class RandomLoader
5974	{
5975	public:
5976	Loader()
5977	{
5978	BackendMakers().report(new RandomFactory);
5979
5980	L<<Logger::Info<<" [RandomBackend] This is the randombackend ("__DATE__", "__TIME__") reporting"<<endl;
5981	}
5982	};
5983
5984	static RandomLoader randomloader;
5985	</programlisting>
5986	This simple backend can be used as an 'overlay'. In other words, it only knows about a single record, another loaded backend would have
5987	to know about the SOA and NS records and such. But nothing prevents us from loading it without another backend.
5988	</para>
5989	<para>
5990	The first part of the code contains the actual logic and should be pretty straightforward. The second part is a boilerplate
5991	'factory' class which PDNS calls to create randombackend instances. Note that a 'suffix' parameter is passed. Real life backends
5992	also declare parameters for the configuration file; these get the 'suffix' appended to them. Note that the "random" in the
5993	constructor denotes the name by which the backend will be known.
5994	</para>
5995	<para>
5996	The third part registers the RandomFactory with PDNS. This is a simple C++ trick which makes sure that this function
5997	is called on execution of the binary or when loading the dynamic module.
5998	</para>
5999	<para>
6000	Please note that a RandomBackend is actually in most PDNS releases. By default it lives on random.example.com, but you can change
6001	that by setting <command>random-hostname</command>.
6002	</para>
6003	<para>
6004	NOTE: this simple backend neglects to handle case properly! For a more complete example, see the full pdns-dev distribution as found on
6005	<ulink url="http://www.powerdns.com/pdns">the website</ulink>.
6006	</para>
6007	</sect2>
6008	<sect2><title>Interface definition</title>
6009	<para>
6010	Classes:
6011	<table>
6012	<title>DNSResourceRecord class</title>
6013	<tgroup cols=2>
6014	<tbody>
6015	<row>
6016	<entry>QType qtype</entry><entry>QType of this record</entry>
6017	</row>
6018	<row>
6019	<entry>string qname</entry><entry>name of this record</entry>
6020	</row>
6021	<row>
6022	<entry>string content</entry><entry>ASCII representation of right hand side</entry>
6023	</row>
6024	<row>
6025	<entry>u_int16_t priority</entry><entry>priority of an MX record.</entry>
6026	</row>
6027	<row>
6028	<entry>u_int32_t ttl</entry><entry>Time To Live of this record</entry>
6029	</row>
6030	<row>
6031	<entry>int domain_id</entry><entry>ID of the domain this record belongs to</entry>
6032	</row>
6033	<row>
6034	<entry>time_t last_modified</entry><entry>If unzero, last time_t this record was changed</entry>
6035	</row>
6036	</tbody>
6037	</tgroup>
6038	</table>
6039	</para>
6040	<para>
6041	<table>
6042	<title>SOAData struct</title>
6043	<tgroup cols=2>
6044	<tbody>
6045	<row>
6046	<entry>string nameserver</entry><entry>Name of the master nameserver of this zone</entry>
6047	</row>
6048	<row>
6049	<entry>string hostmaster</entry><entry>Hostmaster of this domain. May contain an @</entry>
6050	</row>
6051	<row>
6052	<entry>u_int32_t serial</entry><entry>Serial number of this zone</entry>
6053	</row>
6054	<row>
6055	<entry>u_int32_t refresh</entry><entry>How often this zone should be refreshed</entry>
6056	</row>
6057	<row>
6058	<entry>u_int32_t retry</entry><entry>How often a failed zone pull should be retried.</entry>
6059	</row>
6060	<row>
6061	<entry>u_int32_t expire</entry><entry>If zone pulls failed for this long, retire records</entry>
6062	</row>
6063	<row>
6064	<entry>u_int32_t default_ttl</entry><entry>Difficult</entry>
6065	</row>
6066	<row>
6067	<entry>int domain_id</entry><entry>The ID of the domain within this backend. Must be filled!</entry>
6068	</row>
6069	<row>
6070	<entry>DNSBackend *db</entry><entry>Pointer to the backend that feels authoritative for a domain and can act as a slave</entry>
6071	</row>
6072	</tbody>
6073	</tgroup>
6074	</table>
6075	</para>
6076	<para>
6077	Methods:
6078	<variablelist>
6079	<varlistentry>
6080	<term>void lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt=0, int zoneId=-1)</term>
6081	<listitem>
6082	<para>
6083	This function is used to initiate a straight lookup for a record of name 'qdomain' and type 'qtype'.
6084	A QType can be converted into an integer by invoking its <function>getCode()</function> method and into
6085	a string with the <function>getCode()</function>.
6086	</para>
6087	<para>
6088	The original question may or may not be passed in the pointer p. If it is, you can retrieve (from 1.99.11 onwards)
6089	information about who asked the question with the <function>getRemote(DNSPacket *)</function> method. Alternatively,
6090	<function>bool getRemote(struct sockaddr sa, socklen_t len)</function> is available.
6091	</para>
6092	<para>
6093	Note that <command>qdomain</command> can be of any case and that your backend should make sure it is in effect case
6094	insensitive. Furthermore, the case of the original question should be retained in answers returned by <function>get()</function>!
6095	</para>
6096	<para>
6097	Finally, the domain_id might also be passed indicating that only answers from the indicated zone need apply. This
6098	can both be used as a restriction or as a possible speedup, hinting your backend where the answer might be found.
6099	</para>
6100	<para>
6101	If initiated succesfully, as indicated by returning <command>true</command>, answers should be made available over the
6102	<function>get()</function> method.
6103	</para>
6104	<para>
6105	Should throw an AhuException if an error occured accessing the database. Returning otherwise indicates that the query
6106	was started succesfully. If it is known that no data is available, no exception should be thrown! An exception indicates
6107	that the backend considers itself broken - not that no answers are available for a question.
6108	</para>
6109	<para>
6110	It is legal to return here, and have the first call to <function>get()</function> return false. This is interpreted as 'no data'
6111	</para>
6112	</listitem>
6113	</varlistentry>
6114
6115	<varlistentry>
6116	<term>bool list(int domain_id)
6117	<listitem>
6118	<para>
6119	Initiates a list of the indicated domain. Records should then be made available via the <function>get()</function> method.
6120	Need not include the SOA record. If it is, PDNS will not get confused.
6121	</para>
6122	<para>
6123	Should return false if the backend does not consider itself authoritative for this zone.
6124	Should throw an AhuException if an error occured accessing the database. Returning true indicates that data is or should be available.
6125	</para>
6126	</listitem>
6127	</varlistentry>
6128
6129	<varlistentry>
6130	<term>bool get(DNSResourceRecord &rr)</term>
6131	<listitem>
6132	<para>
6133	Request a DNSResourceRecord from a query started by <function>get()</function> of <function>list()</function>. If this functions returns
6134	<command>true</command>, <command>rr</command> has been filled with data. When it returns false, no more data is available,
6135	and <command>rr</command> does not contain new data. A backend should make sure that it either fills out all fields of the
6136	DNSResourceRecord or resets them to their default values.
6137	</para>
6138	<para>
6139	The qname field of the DNSResourceRecord should be filled out with the exact <function>qdomain</function> passed to lookup, preserving
6140	its case. So if a query for 'CaSe.yourdomain.com' comes in and your database contains dat afor 'case.yourdomain.com', the qname field of rr
6141	should contin 'CaSe.yourdomain.com'!
6142	</para>
6143	<para>
6144	Should throw an AhuException in case a database error occurred.
6145	</para>
6146	</listitem>
6147	</varlistentry>
6148
6149	<varlistentry>
6150	<term>bool getSOA(const string &name, SOAData &soadata)</term>
6151	<listitem>
6152	<para>
6153	If the backend considers itself authoritative over domain <function>name</function>, this method should fill out
6154	the passed <command>SOAData</command> structure and return a positive number. If the backend is functioning correctly, but
6155	does not consider itself authoritative, it should return 0. In case of errors, an AhuException should be thrown.
6156	</para>
6157	</listitem>
6158	</varlistentry>
6159	</variablelist>
6160	</para>
6161	</sect2>
6162	</sect1>
6163	<sect1 id="backend-error-reporting"><title>Reporting errors</title>
6164	<para>
6165	To report errors, the Logger class is available which works mostly like an iostream. Example usage is as shown above in the RandomBackend.
6166	Note that it is very important that each line is ended with <command>endl</command> as your message won't be visible otherwise.
6167	</para>
6168	<para>
6169	To indicate the importance of an error, the standard syslog errorlevels are available. They can be set by outputting
6170	<function>Logger::Critical</function>,
6171	<function>Logger::Error</function>,
6172	<function>Logger::Warning</function>,
6173	<function>Logger::Notice</function>,
6174	<function>Logger::Info</function> or
6175	<function>Logger::Debug</function> to <function>L</function>, in descending order of graveness.
6176	</para>
6177	</sect1>
6178	<sect1 id="backend-configuration-details"><title>Declaring and reading configuration details</title>
6179	<para>
6180	It is highly likely that a backend needs configuration details. On launch, these parameters need to be declared with PDNS so it knows it
6181	should accept them in the configuration file and on the commandline. Furthermore, they will be listed in the output of
6182	<command>--help</command>.
6183	</para>
6184	<para>
6185	Declaring arguments is done by implementing the member function <function>declareArguments()</function> in the factory class of your
6186	backend. PDNS will call this method after launching the backend.
6187	</para>
6188	<para>
6189	In the <function>declareArguments()</function> method, the function <function>declare()</function> is available. The exact definitions:
6190	<variablelist>
6191	<varlistentry>
6192	<term>void declareArguments(const string &suffix="")</term>
6193	<listitem>
6194	<para>
6195	This method is called to allow a backend to register configurable parameters. The suffix is the sub-name of this module. There is
6196	no need to touch this suffix, just pass it on to the declare method.
6197	</para>
6198	</listitem>
6199	</varlistentry>
6200
6201	<varlistentry>
6202	<term>void declare(const string &suffix, const string &param, const string &explanation, const string &value)</term>
6203	<listitem>
6204	<para>The suffix is passed to your method, and can be passed on to declare. <command>param</command> is the name of your parameter.
6205	<command>explanation</command> is what will appear in the output of --help. Furthermore, a default value can be supplied in the
6206	<command>value</command> parameter.
6207	</para>
6208	</listitem>
6209	</varlistentry>
6210	</variablelist>
6211	</para>
6212	<para>
6213	A sample implementation:
6214	<programlisting>
6215	void declareArguments(const string &suffix)
6216	{
6217	declare(suffix,"dbname","Pdns backend database name to connect to","powerdns");
6218	declare(suffix,"user","Pdns backend user to connect as","powerdns");
6219	declare(suffix,"host","Pdns backend host to connect to","");
6220	declare(suffix,"password","Pdns backend password to connect with","");
6221	}
6222	</programlisting>
6223	</para>
6224	<para>
6225	After the arguments have been declared, they can be accessed from your backend using the <function>mustDo()</function>,
6226	<function>getArg()</function> and <function>getArgAsNum()</function> methods. The are defined as follows in the DNSBackend class:
6227	</para>
6228	<para>
6229	<variablelist>
6230	<varlistentry>
6231	<term>void setArgPrefix(const string &prefix)</term>
6232	<listitem>
6233	<para>
6234	Must be called before any of the other accessing functions are used. Typical usage is '<function>setArgPrefix("mybackend"+suffix)</function>'
6235	in the constructor of a backend.
6236	</para>
6237	</listitem>
6238	</varlistentry>
6239
6240	<varlistentry>
6241	<term>bool mustDo(const string &key)</term>
6242	<listitem>
6243	<para>
6244	Returns true if the variable <function>key</function> is set to anything but 'no'.
6245	</para>
6246	</listitem>
6247	</varlistentry>
6248
6249	<varlistentry>
6250	<term>const string& getArg(const string &key)</term>
6251	<listitem>
6252	<para>
6253	Returns the exact value of a parameter.
6254	</para>
6255	</listitem>
6256	</varlistentry>
6257
6258	<varlistentry>
6259	<term>int getArgAsNum(const string &key)</term>
6260	<listitem>
6261	<para>
6262	Returns the numerical value of a parameter. Uses <function>atoi()</function> internally
6263	</para>
6264	</listitem>
6265	</varlistentry>
6266	</variablelist>
6267	</para>
6268	<para>
6269	Sample usage from the BindBackend, using the <command>bind-example-zones</command> and <command>bind-config</command>
6270	parameters.
6271	<programlisting>
6272	if(mustDo("example-zones")) {
6273	insert(0,"www.example.com","A","1.2.3.4");
6274	/* ... */
6275	}
6276
6277
6278	if(!getArg("config").empty()) {
6279	BindParser BP;
6280
6281	BP.parse(getArg("config"));
6282	}
6283
6284	</programlisting>
6285	</para>
6286	</sect1>
6287
6288	<sect1 id="rw-backends"><title>Read/write slave-capable backends</title>
6289	<para>
6290	The backends above are 'natively capable' in that they contain all data relevant for a domain and do not pull in data from other nameservers.
6291	To enable storage of information, a backend must be able to do more.
6292	</para>
6293	<para>
6294	Before diving into the details of the implementation some theory is in order. Slave domains are pulled from the master. PDNS needs to
6295	know for which domains it is to be a slave, and for each slave domain, what the IP address of the master is.
6296	</para>
6297	<para>
6298	A slave zone is pulled from a master, after which it is 'fresh', but this is only temporary. In the SOA record of a zone there is a field
6299	which specifies the 'refresh' interval. After that interval has elapsed, the slave nameserver needs to check at the master ff the serial
6300	number there is higher than what is stored in the backend locally.
6301	</para>
6302	<para>
6303	If this is the case, PDNS dubs the domain 'stale', and schedules a transfer of data from the remote. This transfer remains scheduled
6304	until the serial numbers remote and locally are identical again.
6305	</para>
6306	<para>
6307	This theory is implemented by the <function>getUnfreshSlaveInfos</function> method, which is called on all backends periodically.
6308	This method fills a vector of <command>SlaveDomain</command>s with domains that are unfresh and possibly stale.
6309	</para>
6310	<para>
6311	PDNS then retrieves the SOA of those domains remotely and locally and creates a list of stale domains. For each of these domains, PDNS
6312	starts a zonetransfer to resynchronise. Because zone transfers can fail, it is important that the interface to the backend allows
6313	for transaction semantics because a zone might otherwise be left in a halfway updated situation.
6314	</para>
6315	<para>
6316	The following excerpt from the DNSBackend shows the relevant functions:
6317	</para>
6318	<para>
6319	<programlisting>
6320	class DNSBackend {
6321	public:
6322	/* ... */
6323	virtual bool getDomainInfo(const string &domain, DomainInfo &di);
6324	virtual bool isMaster(const string &name, const string &ip);
6325	virtual bool startTransaction(const string &qname, int id);
6326	virtual bool commitTransaction();
6327	virtual bool abortTransaction();
6328	virtual bool feedRecord(const DNSResourceRecord &rr);
6329	virtual void getUnfreshSlaveInfos(vector<DomainInfo>* domains);
6330	virtual void setFresh(int id);
6331	/* ... */
6332	}
6333	</programlisting>
6334	</para>
6335	<para>
6336	The mentioned DomainInfo struct looks like this:
6337	<table>
6338	<title>DomainInfo struct</title>
6339	<tgroup cols=2>
6340	<tbody>
6341	<row>
6342	<entry>int id</entry><entry>ID of this zone within this backend</entry>
6343	</row>
6344	<row>
6345	<entry>string master</entry><entry>IP address of the master of this domain, if any</entry>
6346	</row>
6347	<row>
6348	<entry>u_int32_t serial</entry><entry>Serial number of this zone</entry>
6349	</row>
6350	<row>
6351	<entry>u_int32_t notified_serial</entry><entry>Last serial number of this zone that slaves have seen</entry>
6352	</row>
6353	<row>
6354	<entry>time_t last_check</entry><entry>Last time this zone was checked over at the master for changes</entry>
6355	</row>
6356	<row>
6357	<entry>enum {Master,Slave,Native} kind</entry><entry>Type of zone</entry>
6358	</row>
6359	<row>
6360	<entry>DNSBackend *backend</entry><entry>Pointer to the backend that feels authoritative for a domain and can act as a slave</entry>
6361	</row>
6362	</tbody>
6363	</tgroup>
6364	</table>
6365	</para>
6366	<para>
6367	These functions all have a default implementation that returns false - which explains that these methods can be omitted in simple backends.
6368	Furthermore, unlike with simple backends, a slave capable backend must make sure that the 'DNSBackend *db' field of the SOAData record is filled
6369	out correctly - it is used to determine which backend will house this zone.
6370	<variablelist>
6371	<varlistentry>
6372	<term>bool isMaster(const string &name, const string &ip);</term>
6373	<listitem>
6374	<para>
6375	If a backend considers itself a slave for the domain <command>name</command> and if the IP address in <command>ip</command>
6376	is indeed a master, it should return true. False otherwise. This is a first line of checks to guard against reloading a domain
6377	unnecessarily.
6378	</para>
6379	</listitem>
6380	</varlistentry>
6381	<varlistentry>
6382	<term>void getUnfreshSlaveInfos(vector<DomainInfo>* domains)</term>
6383	<listitem>
6384	<para>
6385	When called, the backend should examine its list of slave domains and add any unfresh ones to the domains vector.
6386	</para>
6387	</listitem>
6388	</varlistentry>
6389	<varlistentry>
6390	<term>bool getDomainInfo(const string &name, DomainInfo & di)</term>
6391	<listitem>
6392	<para>
6393	This is like getUnfreshSlaveInfos, but for a specific domain. If the backend considers itself authoritative for the named
6394	zone, <function>di</function> should be filled out, and 'true' be returned. Otherwise return false.
6395	</para>
6396	</listitem>
6397	</varlistentry>
6398	<varlistentry>
6399	<term>bool startTransaction(const string &qname, int id)</term>
6400	<listitem>
6401	<para>
6402	When called, the backend should start a transaction that can be committed or rolled back atomically later on.
6403	In SQL terms, this function should <command>BEGIN</command> a transaction and <command>DELETE</command> all
6404	records.
6405	</para>
6406	</listitem>
6407	</varlistentry>
6408	<varlistentry>
6409	<term>bool feedRecord(const DNSResourceRecord &rr)</term>
6410	<listitem>
6411	<para>
6412	Insert this record.
6413	</para>
6414	</listitem>
6415	</varlistentry>
6416
6417	<varlistentry>
6418	<term>bool commitTransaction();</term>
6419	<listitem>
6420	<para>
6421	Make the changes effective. In SQL terms, execute <command>COMMIT</command>.
6422	</para>
6423	</listitem>
6424	</varlistentry>
6425
6426	<varlistentry>
6427	<term>bool abortTransaction();</term>
6428	<listitem>
6429	<para>
6430	Abort changes. In SQL terms, execute <command>ABORT</command>.
6431	</para>
6432	</listitem>
6433	</varlistentry>
6434	<varlistentry>
6435	<term>bool setFresh()</term>
6436	<listitem>
6437	<para>
6438	Indicate that a domain has either been updated or refreshed without the need for a retransfer. This causes
6439	the domain to vanish from the vector modified by <function>getUnfreshSlaveInfos()</function>.
6440	</para>
6441	</listitem>
6442	</varlistentry>
6443
6444	</variablelist>
6445	</para>
6446	<para>
6447	PDNS will always call <function>startTransaction()</function> before making calls to <function>feedRecord()</function>.
6448	Although it is likely that <function>abortTransaction()</function> will be called in case of problems, backends should also
6449	be prepared to abort from their destructor.
6450	</para>
6451	<para>
6452	The actual code in PDNS is currently (1.99.9):
6453	<programlisting>
6454	Resolver resolver;
6455	resolver.axfr(remote,domain.c_str());
6456
6457	db->startTransaction(domain, domain_id);
6458
6459	L<<Logger::Error<<"AXFR started for '"<<domain<<"'"<<endl;
6460	Resolver::res_t recs;
6461
6462	while(resolver.axfrChunk(recs)) {
6463	for(Resolver::res_t::const_iterator i=recs.begin();i!=recs.end();++i) {
6464	db->feedRecord(*i);
6465	}
6466	}
6467	db->commitTransaction();
6468	db->setFresh(domain_id);
6469	L<<Logger::Error<<"AXFR done for '"<<domain<<"'"<<endl;
6470	</programlisting>
6471	</para>
6472	<sect2><title>Supermaster/Superslave capability</title>
6473	<para>
6474	A backend that wants to act as a 'superslave' for a master should implement the following method:
6475	<programlisting>
6476	class DNSBackend
6477	{
6478	virtual bool superMasterBackend(const string &ip, const string &domain, const vector<DNSResourceRecord>&nsset, string account, DNSBackend *db)
6479	};
6480	</programlisting>
6481	This function gets called with the IP address of the potential supermaster, the domain it is sending a notification for and the set of NS records
6482	for this domain at that IP address.
6483	</para>
6484	<para>
6485	Using the supplied data, the backend needs to determine if this is a bonafide 'supernotification' which should be honoured. If it decides that it
6486	should, the supplied pointer to 'account' needs to be filled with the configured name of the supermaster (if accounting is desired), and the
6487	db needs to be filled with a pointer to your backend.
6488	</para>
6489	<para>
6490	Supermaster/superslave is a complicated concept, if this is all unclear see <xref linkend="supermaster">.
6491	</sect2>
6492	</sect1>
6493	<sect1 id="master-backends"><title>Read/write master-capable backends</title>
6494	<para>
6495	In order to be a useful master for a domain, notifies must be sent out whenever a domain is changed. Periodically, PDNS
6496	queries backends for domains that may have changed, and sends out notifications for slave nameservers.
6497	</para>
6498	<para>
6499	In order to do so, PDNS calls the <function>getUpdatedMasters()</function> method. Like the <function>getUnfreshSlaveInfos()</function>
6500	function mentioned above, this should add changed domain names to the vector passed.
6501	</para>
6502	<para>
6503	The following excerpt from the DNSBackend shows the relevant functions:
6504	</para>
6505	<para>
6506	<programlisting>
6507	class DNSBackend {
6508	public:
6509	/* ... */
6510	virtual void getUpdatedMasters(vector<DomainInfo>* domains);
6511	virtual void setNotifed(int id, u_int32_t serial);
6512	/* ... */
6513	}
6514	</programlisting>
6515	</para>
6516	<para>
6517	These functions all have a default implementation that returns false - which explains that these methods can be omitted in simple backends.
6518
6519	Furthermore, unlike with simple backends, a slave capable backend must make sure that the 'DNSBackend *db' field of the SOAData record is filled
6520	out correctly - it is used to determine which backend will house this zone.
6521
6522	<variablelist>
6523	<varlistentry>
6524	<term>void getUpdatedMasters(vector<DomainInfo>* domains)</term>
6525	<listitem>
6526	<para>
6527	When called, the backend should examine its list of master domains and add any changed ones to the DomainInfo vector
6528	</para>
6529	</listitem>
6530	</varlistentry>
6531	<varlistentry>
6532	<term>bool setNotified(int domain_id, u_int32_t serial)</term>
6533	<listitem>
6534	<para>
6535	Indicate that notifications have been queued for this domain and that it need not be considered 'updated' anymore
6536	</para>
6537	</listitem>
6538	</varlistentry>
6539	</variablelist>
6540	</para>
6541	</sect1>
6542
6543	</appendix>
6544	<appendix id="compiling-powerdns"><title>Compiling PowerDNS</title>
6545	<para>
6546	The PowerDNS source is separated from many of its modules. The main PowerDNS source tree however is able
6547	to pull in certain files for creating packaged releases.
6548	</para>
6549	<para>
6550	First download the source or retrieve from anoncvs.powerdns.com (module 'powerdns'). If from cvs, you need to execute
6551	<filename>./bootstrap</filename> to have the GNU autotools build the configure script and the Makefiles.
6552	</para>
6553	<para>
6554	The run ./configure, followed by 'make'. PowerDNS prefers being compiled with GCC 3.2 but 2.95.4 and 3.0.4 will also work on most systems.
6555	It will not compile on Debian Potato because that lacks the <filename>sstream</filename> include file.
6556	</para>
6557	<para>
6558	After compiling, the <filename>./installer</filename> script can be used to install.
6559	</para>
6560	<sect1><title>Configuring external modules with PowerDNS</title>
6561	<para>
6562	A module needs to see the PowerDNS sources. See the INSTALL file of a module on how to configure this.
6563	</para>
6564	</sect1>
6565	</book>

Note: See TracBrowser for help on using the browser.

Context Navigation

root/trunk/pdns/pdns/docs/pdns.sgml @ 15

Download in other formats: