</bookinfo>
<chapter id="powerdns">
- <title>The PowerDNS dynamic nameserver</title>
+ <title>The PowerDNS Authoritative Server</title>
<para>
- The PowerDNS daemon is a versatile nameserver which supports a large number
+ The PowerDNS Authoritative Server is a versatile nameserver which supports a large number
of backends. These backends can either be <link linkend="bindbackend">plain zone files</link> or be
<link linkend="pipebackend">more dynamic</link> in nature. Additionally, through use of clever programming techniques,
PowerDNS offers very high domain resolution performance.
Prime examples of backends include relational databases, but also (geographical) load balancing and failover algorithms.
</para>
<para>
- The company is called PowerDNS.COM BV, the nameserver daemon is called PDNS.
+ The company is called PowerDNS.COM BV, the nameserver daemons are called PowerDNS Authoritative Server and PowerDNS Recursor.
</para>
<sect1 id="function-design"><title>Function & design of PDNS</title>
</para>
<para>
Another prime goal is <link linkend="security">security</link>. By the use of language features, the PDNS source code
- is very small (in the order of 10.000 lines) which makes auditing easy. In the same way, library features have been used
+ is reasonably small which makes auditing easy. In the same way, library features have been used
to mitigate the risks of buffer overflows.
</para>
<para>
- Finally, PDNS is able to give a lot of <link linkend="monitoring">statistics</link> on its operation which is both helpful in
+ Finally, PowerDNS is able to give a lot of <link linkend="monitoring">statistics</link> on its operation which is both helpful in
determining the scalability of an installation as well as for spotting problems.
</para>
</sect1>
<listitem>
<para>
PowerDNS now prints out a warning when running with legacy LinuxThreads implementation instead of the high performance NPTL
- library, see <xref linkend="nptl"/>. c455.
+ library. c455.
</para>
</listitem>
<listitem>
<sect1 id="configuring-mysql"><title>Example: configuring MySQL</title>
<para>
Connect to MySQL as a user with sufficient privileges and issue the following commands:
- <programlisting><xi:include href="../../modules/gmysqlbackend/no-dnssec.schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ <programlisting><xi:include href="../../modules/gmysqlbackend/schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
Now we have a database and an empty table. PDNS should now be able to launch in monitor mode and display no errors:
<chapter id="performance"><title>Authoritative Server Performance</title>
<sect1><title>General advice</title>
<para>
- In general, best performance is achieved on recent Linux 2.6 kernels and using MySQL, although many of the largest PowerDNS
- installations are based on PostgreSQL. FreeBSD appears to achieve lower packet rates both for the PowerDNS recursor as for the
- authoritative nameserver, this is still being investigated. No comparative measurements have been done for Solaris installations.
- </para>
- <para>
- On Linux, make sure to read <xref linkend="nptl"/>.
+ In general, best performance is achieved on recent Linux 3.x kernels and using MySQL, although many of the largest PowerDNS
+ installations are based on PostgreSQL. FreeBSD also performs very well.
</para>
<para>
Database servers can require configuration to achieve decent performance. It is especially worth noting that
several vendors ship PostgreSQL with a slow default configuration.
</para>
- </sect1>
- <sect1 id="nptl">
- <title>Native Posix Thread Library vs LinuxThreads</title>
- <para>
- To get the best performance under Linux, especially on SMP
- systems, the use of NPTL is advised. The difference in
- performance can be over a factor of ten in some circumstances.
- </para>
- <para>
- NPTL is the default library on modern Linux distributions, so
- there is generally not a problem, except if you use a
- statically compiled version that, for portability reasons,
- defaults to LinuxThreads. This includes all .deb and .rpm files
- provided by us up to and including 2.9.18.
- </para>
- <para>
- When running a PowerDNS-provided static binary of 2.9.18 or
- lower, it may make sense to recompile, or to upgrade to a
- newer version, if available. When recompiling, be sure to use
- a supported compiler, like g++ >3.2. You might also consider
- moving to a distribution supplied version.
- </para>
- <para>
- A good indication that your installation might benefit from
- such an upgrade is to watch the 'cs' count in the output of
- vmstat 1. If this is very high (> 10000), you are suffering
- from a LinuxThreads performance problem called 'overspin'.
- </para>
- <para>
- Thanks are due to L. Bunt Jackson who noted the static
- compilation problem in an article in Dr. Dobb's Journal.
- </para>
+ <para>
+ <warning><para>When deploying (large scale) IPv6, please be aware some
+ Linux distributions leave IPv6 routing cache tables at very small
+ default values. Please check and if necessary raise 'sysctl
+ net.ipv6.route.max_size'.</para></warning>
+ </para>
</sect1>
<sect1 id="performance-settings">
<title>Performance related settings</title>
</para>
</note>
<para>
- An GSQL Backend schema change is necessary for new features.
- For MySQL:
- <screen>
-ALTER TABLE records ADD disabled BOOLEAN;
-UPDATE records SET disabled=0;
-</screen>
- For PostgreSQL:
- <screen>
-ALTER TABLE records ADD disabled BOOLEAN;
-UPDATE records SET disabled=false;
-</screen>
- For SQLite 3:
- <screen>
-ALTER TABLE records ADD disabled BOOLEAN;
-UPDATE records SET disabled=0;
-</screen>
- For Oracle:
+ <warning>
+ <para>
+ The default database schema has changed. The database update below is mandatory.
+ </para>
+ <para>
+ If custom queries are in use, they probably need an update.
+ </para>
+ </warning>
+ </para>
+ <para>
+ For gmysql backend with nodnssec schema:
+ <programlisting><xi:include href="../../modules/gmysqlbackend/nodnssec-3.x_to_3.4_schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For gmysql backend with dnssec schema:
+ <programlisting><xi:include href="../../modules/gmysqlbackend/dnssec-3.x_to_3.4_schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For gpgsql backend with nodnssec schema:
+ <programlisting><xi:include href="../../modules/gpgsqlbackend/nodnssec-3.x_to_3.4_schema.pgsql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For gpgsql backend with dnssec schema:
+ <programlisting><xi:include href="../../modules/gpgsqlbackend/dnssec-3.x_to_3.4_schema.pgsql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For gsqlite3 backend with nodnssec schema:
+ <programlisting><xi:include href="../../modules/gsqlite3backend/nodnssec-3.x_to_3.4_schema.sqlite3.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For gsqlite3 backend with dnssec schema:
+ <programlisting><xi:include href="../../modules/gsqlite3backend/dnssec-3.x_to_3.4_schema.sqlite3.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ For goracle backend:
<screen>
-ALTER TABLE records ADD disabled INT;
-UPDATE records SET disabled=0;
-</screen>
+ALTER TABLE records ADD disabled INT DEFAULT 0;
+ALTER TABLE records MODIFY auth INT DEFAULT 1;
+
+UPDATE records SET auth=1 WHERE auth IS NULL;
+ </screen>
</para>
</sect1>
-
</chapter>
+
<chapter id="powerdnssec-auth">
<title>Serving authoritative DNSSEC data</title>
<para>
</para>
</listitem>
</varlistentry>
+ <varlistentry><term>carbon-ourname=...</term>
+ <listitem><para>
+ If sending carbon updates, if set, this will override our hostname. See <xref linkend="metrics-carbon"/>. Available beyond 3.5.3.
+ </para></listitem></varlistentry>
+ <varlistentry><term>carbon-server=...</term>
+ <listitem><para>
+ If set to an IP or IPv6 address, will send all available metrics to this server
+ via the carbon protocol, which is used by graphite and metronome. See <xref linkend="metrics-carbon"/>. Available beyond 3.5.3.
+ </para></listitem></varlistentry>
+ <varlistentry><term>carbon-interval=...</term>
+ <listitem><para>
+ If sending carbon updates, this is the interval between them in seconds. See <xref linkend="metrics-carbon"/>. Available beyond 3.5.3.
+ </para></listitem></varlistentry>
+
<varlistentry><term>chroot</term>
<listitem><para>
If set, chroot to this directory for more security. See <xref linkend="security"/>.
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>loglevel</term>
+ <listitem>
+ <para>
+ Amount of logging. Higher is more, more logging may destroy performance. Available since 3.6.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>log-common-errors</term>
<listitem>
very heavy duty use.
</para>
</listitem>
+ <listitem>
+ <para>When deploying (large scale) IPv6, please be aware some
+ Linux distributions leave IPv6 routing cache tables at very small
+ default values. Please check and if necessary raise 'sysctl
+ net.ipv6.route.max_size'.</para>
+ </listitem>
<listitem>
<para>
For older versions <3.2: If you need it, try <command>--fork</command>, this will fork the daemon into two halves, allowing it to benefit from a second CPU.
<listitem><para>
Seconds to store packets in the PacketCache. See <xref linkend="packetcache"/>.
</para></listitem></varlistentry>
+ <varlistentry><term>carbon-ourname=...</term>
+ <listitem><para>
+ If sending carbon updates, if set, this will override our hostname. See <xref linkend="metrics-carbon"/>. Available beyond 3.3.1.
+ </para></listitem></varlistentry>
+ <varlistentry><term>carbon-server=...</term>
+ <listitem><para>
+ If set to an IP or IPv6 address, will send all available metrics to this server
+ via the carbon protocol, which is used by graphite and metronome. See <xref linkend="metrics-carbon"/>. Available beyond 3.3.1.
+ </para></listitem></varlistentry>
+ <varlistentry><term>carbon-interval=...</term>
+ <listitem><para>
+ If sending carbon updates, this is the interval between them in seconds. See <xref linkend="metrics-carbon"/>. Available beyond 3.3.1.
+ </para></listitem></varlistentry>
+
<varlistentry><term>chroot=...</term>
<listitem><para>
If set, chroot to this directory for more security. See <xref linkend="security"/>.
<listitem><para>
Entropy source (like /dev/urandom).
</para></listitem></varlistentry>
+ <varlistentry><term>experimental-dname-processing=...</term>
+ <listitem><para>
+ Synthesise CNAME records from DNAME records as required. This approximately doubles query load. Do not combine
+ with DNSSEC!
+ </para></listitem></varlistentry>
<varlistentry><term>fancy-records=...</term>
<listitem><para>
Process URL and MBOXFW records. See <xref linkend="fancy-records"/>.
</variablelist>
</para>
</chapter>
+ <chapter id="metrics-carbon"><title>PowerDNS Metrics, and how to display them</title>
+ <warning>
+ <para>
+ Available in releases after PowerDNS Authoritative Server 3.3.1 and PowerDNS Recursor 3.5.3.
+ </para>
+ </warning>
+ <para>
+ Both PowerDNS daemons generate ample metrics which can be used to monitor performance. These metrics
+ can be polled using the rec_control and pdns_control commands, and they are also available via the http-based API.
+ Finally, they can be pushed to a Carbon/Graphite server, either native carbon, or our own Metronome implementation.
+ </para>
+ <para>
+ For carbon/graphite/metronome, we use the following namespace. Everything starts with 'pdns.', which is then followed
+ by the local hostname. Thirdly, we add either 'auth' or 'recursor' to siginify the daemon generating the metrics.
+ This is then rounded off with the actual name of the metric. As an example: 'pdns.ns1.recursor.questions'.
+ </para>
+ <para>
+ Care has been taken to make the sending of statistics as unobtrusive as possible, the daemons will not be
+ hindered by an unreachable carbon server, timeouts or connection refused situations.
+ </para>
+ <para>
+ To benefit from our carbon/graphite support, either install Graphite, or use our own lightweight
+ statistics daemon, Metronome, currently available on <ulink url="https://github.com/ahupowerdns/metronome/">GitHub</ulink>.
+ </para>
+ <para>
+ Secondly, set carbon-server, possibly carbon-interval, possibly carbon-ourname in the configuration.
+ </para>
+ </chapter>
+
+
<appendix id="backends-detail"><title>Backends in detail</title>
<para>
This appendix lists several of the available backends in more detail
<row><entry>Autoserial</entry><entry>No</entry></row>
<row><entry>Case</entry><entry>Depends</entry></row>
<row><entry>DNSSEC</entry><entry>Partial, no delegation, no key storage</entry></row>
+ <row><entry>Disabled data</entry><entry>No</entry></row>
+ <row><entry>Comments</entry><entry>No</entry></row>
<row><entry>Module name</entry><entry>pipe</entry></row>
<row><entry>Launch name</entry><entry>pipe</entry></row>
</tbody>
<row><entry>Autoserial</entry><entry>No</entry></row>
<row><entry>Case</entry><entry>Depends</entry></row>
<row><entry>DNSSEC</entry><entry>Yes, no key storage</entry></row>
+ <row><entry>Disabled data</entry><entry>No</entry></row>
+ <row><entry>Comments</entry><entry>No</entry></row>
<row><entry>Module name</entry><entry>built in</entry></row>
<row><entry>Launch name</entry><entry>random</entry></row>
</tbody>
<row><entry>Case</entry><entry>All lower</entry></row>
<row><entry>DNSSEC</entry><entry>Yes (set gmysql-dnssec or gpgsql-dnssec)</entry></row>
<row><entry>Disabled data</entry><entry>Yes (v3.4 and up)</entry></row>
+ <row><entry>Comments</entry><entry>Yes (v3.4 and up)</entry></row>
<row><entry>Module name < 2.9.3</entry><entry>pgmysql</entry></row>
<row><entry>Module name > 2.9.2</entry><entry>gmysql and gpgsql</entry></row>
<row><entry>Launch name</entry><entry>gmysql and gpgsql2 and gpgsql</entry></row>
</para>
<para>
The default setup conforms to the following schema:
- <programlisting><xi:include href="../../modules/gmysqlbackend/no-dnssec.schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ <programlisting><xi:include href="../../modules/gmysqlbackend/schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
</para>
<para>
Zone2sql with the --gmysql flag also assumes this layout is in place.
</para>
- <para>
- To support or migrate to DNSSEC, the following SQL statements must be executed:
- <programlisting><xi:include href="../../modules/gmysqlbackend/dnssec.schema.mysql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
- </para>
<para>
For full migration notes, please see <xref linkend="dnssec-migration"/>.
</para>
<sect2><title>PostgreSQL specifics</title>
<para>
The default setup conforms to the following schema, which you should add to a PostgreSQL database.
- <programlisting><xi:include href="../../modules/gpgsqlbackend/no-dnssec.schema.pgsql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ <programlisting><xi:include href="../../modules/gpgsqlbackend/schema.pgsql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
</para>
<para>
Zone2sql with the --gpgsql flag also assumes this layout is in place.
<para>
This schema contains all elements needed for master, slave and superslave operation.
</para>
- <para>
- To support DNSSEC or to migrate to DNSSEC, the following statements have to be issued:
- <programlisting><xi:include href="../../modules/gpgsqlbackend/dnssec.schema.pgsql.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
-</para>
<para>
For full migration notes, please see <xref linkend="dnssec-migration"/>.
</para>
</variablelist>
</para>
</sect2>
+ <sect2><title>Comments queries</title>
+ <para>
+ For listing/modifying comments. For defaults, please see <command>pdns_server --load=BACKEND --config</command>.
+ <variablelist>
+ <varlistentry>
+ <term>list-comments-query</term>
+ <listitem>
+ <para>
+ Called to get all comments in a zone.
+ Returns fields: domain_id, name, type, modified_at, account, comment.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>insert-comment-query</term>
+ <listitem>
+ <para>
+ Called to create a single comment for a specific RRSet.
+ Given fields: domain_id, name, type, modified_at, account, comment
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>delete-comment-rrset-query</term>
+ <listitem>
+ <para>
+ Called to delete all comments for a specific RRset.
+ Given fields: domain_id, name, type
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>delete-comments-query</term>
+ <listitem>
+ <para>
+ Called to delete all comments for a zone. Usually called before deleting the entire zone.
+ Given fields: domain_id
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
<sect2><title>Fancy records</title>
<warning><para>Fancy records are unsupported as of version 3.0</para></warning>
<para>
<row><entry>Superslave</entry><entry>Yes</entry></row>
<row><entry>Autoserial</entry><entry>Yes</entry></row>
<row><entry>DNSSEC</entry><entry>Yes</entry></row>
+ <row><entry>Comments</entry><entry>No</entry></row>
<row><entry>Module name</entry><entry>oracle</entry></row>
<row><entry>Launch name</entry><entry>oracle</entry></row>
</tbody>
<row><entry>Slave</entry><entry>Yes</entry></row>
<row><entry>Superslave</entry><entry>Yes</entry></row>
<row><entry>DNSSEC</entry><entry>gsqlite3 only (set gsqlite3-dnssec)</entry></row>
+ <row><entry>Disabled data</entry><entry>gsqlite3 only</entry></row>
+ <row><entry>Comments</entry><entry>gsqlite3 only</entry></row>
<row><entry>Module name</entry><entry>gsqlite and gsqlite3</entry></row>
<row><entry>Launch name</entry><entry>gsqlite and gsqlite3</entry></row>
</tbody>
Before you can use this backend you first have to set it up and fill it with data.
The default setup conforms to the following schema:
- <programlisting><xi:include href="../../modules/gsqlite3backend/no-dnssec.schema.sqlite3.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
+ <programlisting><xi:include href="../../modules/gsqlite3backend/schema.sqlite3.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
</para>
<para>
This schema contains all elements needed for master, slave and superslave operation.
</para>
- <para>
- To support DNSSEC, or to migrate to DNSSEC, the following statements must be issued:
- </para>
- <para>
- <programlisting><xi:include href="../../modules/gsqlite3backend/dnssec.schema.sqlite3.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
- </para>
- <para>
- For full migration notes, please see <xref linkend="dnssec-migration"/>.
- </para>
<para>
After you have created the database you probably want to fill it with data.
If you have a BIND zone file it's as easy as: <command>zone2sql --zone=myzonefile --gmysql | sqlite powerdns.sqlite</command>, but
<row><entry>Superslave</entry><entry>No</entry></row>
<row><entry>Autoserial</entry><entry>Yes</entry></row>
<row><entry>DNSSEC</entry><entry>No</entry></row>
+ <row><entry>Disabled data</entry><entry>No</entry></row>
+ <row><entry>Comments</entry><entry>No</entry></row>
<row><entry>Module name</entry><entry>db2</entry></row>
<row><entry>Launch name</entry><entry>db2</entry></row>
<row><entry>Superslave</entry><entry>Experimental</entry></row>
<row><entry>Autoserial</entry><entry>No</entry></row>
<row><entry>DNSSEC</entry><entry>Yes, but no key storage</entry></row>
+ <row><entry>Disabled data</entry><entry>No</entry></row>
+ <row><entry>Comments</entry><entry>No</entry></row>
<row><entry>Module name</entry><entry>none (built in)</entry></row>
<row><entry>Launch</entry><entry>bind</entry></row>
</tbody>
The Lua backend is a full service that can allows a Lua script to provide answers to DNS queries.
</para>
<para>
- More details can be found <ulink url="http://wiki.powerdns.com/cgi-bin/trac.fcgi/browser/trunk/pdns/modules/luabackend/README">here</ulink>, or in
+ More details can be found <ulink url="https://github.com/PowerDNS/pdns/blob/master/modules/luabackend/README">here</ulink>, or in
<filename>modules/luabackend/README</filename>, part of the PowerDNS Authoritative Server distribution.
</para>
</sect1>
projects / thirdparty / pdns.git / blobdiff