]> granicus.if.org Git - pdns/commitdiff
Split some content to common, finish recursor
authorPieter Lexis <pieter@plexis.eu>
Tue, 12 Aug 2014 15:07:35 +0000 (17:07 +0200)
committerPieter Lexis <pieter@plexis.eu>
Tue, 25 Nov 2014 19:11:10 +0000 (20:11 +0100)
14 files changed:
pdns/docs/markdown/authoritative/installation.md
pdns/docs/markdown/authoritative/performance.md
pdns/docs/markdown/authoritative/settings.md
pdns/docs/markdown/changelog.md
pdns/docs/markdown/common/logging.md [moved from pdns/docs/markdown/authoritative/logging.md with 59% similarity]
pdns/docs/markdown/common/security.md [moved from pdns/docs/markdown/authoritative/security.md with 70% similarity]
pdns/docs/markdown/recursor/index.md
pdns/docs/markdown/recursor/performance.md
pdns/docs/markdown/recursor/running.md [new file with mode: 0644]
pdns/docs/markdown/recursor/scripting.md
pdns/docs/markdown/recursor/security.md [new file with mode: 0644]
pdns/docs/markdown/recursor/settings.md
pdns/docs/markdown/recursor/stats.md
pdns/docs/mkdocs.yml

index 6e0d4fce2fae5fe23d28ac5ad4e9134e0161045a..a13baa85c4d2160f5f2c88d88d1344d8d1cbd1c9 100644 (file)
@@ -69,4 +69,4 @@ Dumps a lot of statistics of a running PDNS daemon. It is also possible to singl
 Show a single statistic, as present in the output of the **dump**.
 
 `mrtg`:
-See the performance [monitoring](logging.md#performance-monitoring) documentation.
+See the performance [monitoring](../common/logging.md#performance-monitoring) documentation.
index 7b3e6c778458e72df8ef10c9e2560d0eba51f184..d518c12c7b42e4b18923b71085a55416b21bfde1 100644 (file)
@@ -17,7 +17,7 @@ Another very important setting is [`cache-ttl`](settings.md#cache-ttl). PDNS cac
 
 Some PDNS operators set cache-ttl to many hours or even days, and use [`pdns_control`](../appendix/pdns-internals.md#pdns_control)` purge` to selectively or globally notify PDNS of changes made in the backend. Also look at the [Query Cache](#query-cache) described in this chapter. It may materially improve your performance.
 
-To determine if PDNS is unable to keep up with packets, determine the value of the [`qsize-q`](logging.md#counters) variable. This represents the number of packets waiting for database attention. During normal operations the queue should be small.
+To determine if PDNS is unable to keep up with packets, determine the value of the [`qsize-q`](../common/logging.md#counters) variable. This represents the number of packets waiting for database attention. During normal operations the queue should be small.
 
 Logging truly kills performance as answering a question from the cache is an order of magnitude less work than logging a line about it. Busy sites will prefer to turn [`log-dns-details`](settings.md#log-dns-details) off.
 
@@ -38,3 +38,46 @@ Most gain is made from caching negative entries, ie, queries that have no answer
 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 then take up to 60 seconds to appear. Changes to existing records however do not fall under the negative query ttl ([`negquery-cache-ttl`](settings.md#negquery-cache-ttl)), but under the generic [`query-cache-ttl`](settings.md#query-cache-ttl) which defaults to 20 seconds.
 
 The default values should work fine for many sites. When tuning, keep in mind that the Query Cache mostly saves database access but that the Packet Cache also saves a lot of CPU because 0 internal processing is done when answering a question from the Packet Cache.
+
+# Performance Monitoring
+## Counters & variables
+A number of counters and variables are set during PDNS Authoritative Server operation.
+
+### Counters
+* **corrupt-packets**: Number of corrupt packets received
+* **latency**: Average number of microseconds a packet spends within PDNS
+* **packetcache-hit**: Number of packets which were answered out of the cache
+* **packetcache-miss**: Number of times a packet could not be answered out of the cache
+* **packetcache-size**: Amount of packets in the packetcache
+* **qsize-a**: Size of the queue before the transmitting socket.
+* **qsize-q**: Number of packets waiting for database attention
+* **servfail-packets**: Amount of packets that could not be answered due to database problems
+* **tcp-answers**: Number of answers sent out over TCP
+* **tcp-questions**: Number of questions received over TCP
+* **timedout-questions**: Amount of packets that were dropped because they had to wait too long internally
+* **udp-answers**: Number of answers sent out over UDP
+* **udp-questions**: Number of questions received over UDP
+
+### Ring buffers
+Besides counters, PDNS also maintains the ringbuffers. A ringbuffer records events, each new event gets a place in the buffer until it is full. When full, earlier entries get overwritten, hence the name 'ring'.
+
+By counting the entries in the buffer, statistics can be generated. These statistics can currently only be viewed using the webserver and are in fact not even collected without the webserver running.
+
+The following ringbuffers are available:
+
+* **logmessages**: All messages logged
+* **noerror-queries**: Queries for existing records but for a type we don't have.
+Queries for, say, the AAAA record of a domain, when only an A is available. Queries are listed in the following format: name/type. So an AAAA query for pdns.powerdns.com looks like pdns.powerdns.com/AAAA.
+* **nxdomain-queries**: Queries for non-existing records within existing domains.
+If PDNS knows it is authoritative over a domain, and it sees a question for a record in that domain that does not exist, it is able to send out an authoritative 'no such domain' message. Indicates that hosts are trying to connect to services really not in your zone.
+* **udp-queries**: All UDP queries seen.
+* **remotes**: Remote server IP addresses.
+Number of hosts querying PDNS. Be aware that UDP is anonymous - person A can send queries that appear to be coming from person B.
+* **remote-corrupts**: Remotes sending corrupt packets.
+Hosts sending PDNS broken packets, possibly meant to disrupt service. Be aware that UDP is anonymous - person A can send queries that appear to be coming from person B.
+* **remote-unauth**: Remotes querying domains for which we are not authoritative.
+It may happen that there are misconfigured hosts on the internet which are configured to think that a PDNS installation is in fact a resolving nameserver. These hosts will not get useful answers from PDNS. This buffer lists hosts sending queries for domains which PDNS does not know about.
+* **servfail-queries**: Queries that could not be answered due to backend errors.
+For one reason or another, a backend may be unable to extract answers for a certain domain from its storage. This may be due to a corrupt database or to inconsistent data. When this happens, PDNS sends out a 'servfail' packet indicating that it was unable to answer the question. This buffer shows which queries have been causing servfails.
+* **unauth-queries**: Queries for domains that we are not authoritative for.
+If a domain is delegated to a PDNS instance, but the backend is not made aware of this fact, questions come in for which no answer is available, nor is the authority. Use this ringbuffer to spot such queries.
index 144e925193d1c35ebf334b79f83302ccab4a5f19..25d9ba310536d948bfdc2555681db09ff56dedc8 100644 (file)
@@ -341,12 +341,12 @@ When queried for its version over DNS (`dig chaos txt version.bind @pdns.ip.addr
 * Boolean
 * Default: no
 
-Start a webserver for monitoring. See ["Performance Monitoring"](logging.md#performance-monitoring).
+Start a webserver for monitoring. See ["Performance Monitoring"](../common/logging.md#performance-monitoring).
 
 ## `webserver-address`
 * IP Address
 * Default: 127.0.0.1
-IP Address of webserver to listen on. See ["Performance Monitoring"](logging.md#performance-monitoring).
+IP Address of webserver to listen on. See ["Performance Monitoring"](../common/logging.md#performance-monitoring).
 
 ## `webserver-allow-from`
 * IP ranges
@@ -355,17 +355,17 @@ Webserver access is only allowed from these subnets
 ## `webserver-password`
 * String
 * Default: unset
-The plaintext password required for accessing the webserver. See ["Performance Monitoring"](logging.md#performance-monitoring).
+The plaintext password required for accessing the webserver. See ["Performance Monitoring"](../common/logging.md#performance-monitoring).
 
 ## `webserver-port`
 * Integer
 * Default: 8001
-The port where webserver to listen on. See ["Performance Monitoring"](logging.md#performance-monitoring).
+The port where webserver to listen on. See ["Performance Monitoring"](../common/logging.md#performance-monitoring).
 
 ## `webserver-print-arguments`
 * Boolean
 * Default: no
-If the webserver should print arguments. See ["Performance Monitoring"](logging.md#performance-monitoring).
+If the webserver should print arguments. See ["Performance Monitoring"](../common/logging.md#performance-monitoring).
 
 ## `wildcard-url`
 Check for wildcard URL records.
index 522ae41fca8b008a047433ae62f8281bb2c534a3..02ced9f23925df95a58fc5613f1e63bb520d584f 100644 (file)
@@ -1475,7 +1475,7 @@ A good article on DNS spoofing can be found [here](http://www.securesphere.net/d
 **Warning**: Because of recent DNS based denial of service attacks, running an open recursor has become a security risk. Therefore, unless configured otherwise this version of PowerDNS will only listen on localhost, which means it does not resolve for hosts on your network. To fix, configure the **local-address** setting with all addresses you want to listen on. Additionally, by default service is restricted to RFC 1918 private IP addresses. Use **allow-from** to selectively open up the recursor for your own network. See [pdns\_recursor settings](recursor/settings.md#allow-from "pdns_recursor settings") for details.
 
 ## Important new features of the PowerDNS recursor 3.0
--   Best spoofing protection and detection we know of. Not only is spoofing made harder by using a new network address for each query, PowerDNS detects when an attempt is made to spoof it, and temporarily ignores the data. For details, see [Anti-spoofing](recursor/anti-spoofing.md "Anti-spoofing").
+-   Best spoofing protection and detection we know of. Not only is spoofing made harder by using a new network address for each query, PowerDNS detects when an attempt is made to spoof it, and temporarily ignores the data. For details, see [Anti-spoofing](recursor/security.md "Anti-spoofing").
 -   First nameserver to benefit from epoll/kqueue/Solaris completion ports event reporting framework, for stellar performance.
 -   Best statistics of any recursing nameserver we know of, see [Statistics](recursor/stats.md "Statistics").
 -   Last-recently-used based cache cleanup algorithm, keeping the 'best' records in memory
@@ -2406,7 +2406,7 @@ Developers: this version is compatible with 1.99.11 backends.
 -   Documentation bug - postgresql create/index statements created a duplicate index. If you've previously copy pasted the commands and not noticed the error, execute **CREATE INDEX rec\_name\_index ON records(name)** to remedy. Thanks to Jeff Miller for reporting this. This also lead to depressingly slow 'ANY' lookups for those of you doing benchmarks.
 
 ## Features
--   pdns\_control (see [pdns\_control](appendix/pdns-internals.html#pdnscontrol "pdns_control")) now opens the local end of its socket in `/tmp` instead of next to the remote socket (by default `/var/run`). This eases the way for allowing non-root access to pdns\_control. When running chrooted (see [Chapter 7, *Security settings & considerations*](authoritative/security.md "Security settings & considerations")), the local socket again moves back to `/var/run`.
+-   pdns\_control (see [pdns\_control](appendix/pdns-internals.html#pdnscontrol "pdns_control")) now opens the local end of its socket in `/tmp` instead of next to the remote socket (by default `/var/run`). This eases the way for allowing non-root access to pdns\_control. When running chrooted (see [Chapter 7, *Security settings & considerations*](common/security.md "Security settings & considerations")), the local socket again moves back to `/var/run`.
 -   pdns\_control now has a 'version' command. See [Section 1.1, “pdns\_control”](pdns-internals.html#pdnscontrol "1.1. pdns_control").
 
 # Version 1.99.11 Prerelease
@@ -2435,7 +2435,7 @@ PostgreSQL users should be aware that while 1.99.10 works with the schema as pre
 -   PDNS can now act as a master, sending out notifications in case of changes and allowing slaves to AXFR. Big rewording of replication support, domains are now either 'native', 'master' or 'slave'. See [Master/Slave operation & replication](authoritative/modes-of-operation.md "Master/Slave operation & replication") for lots of details.
 -   **Zone2sql** in PostgreSQL mode now populates the 'domains' table for easy master, slave or native replication support.
 -   Ability to run on IPv6 transport only
--   Logging can now happen under a 'facility' so all PDNS messages appear in their own file. See [Operational logging using syslog](authoritative/logging.md "Operational logging using syslog").
+-   Logging can now happen under a 'facility' so all PDNS messages appear in their own file. See [Operational logging using syslog](common/logging.md "Operational logging using syslog").
 -   Different OS releases of PDNS now get different install path defaults. Thanks to Mark Lastdrager for nagging about this and to Nero Imhard and Frederique Rijsdijk for suggesting saner defaults.
 -   Infrastructure for 'also-notify' statements added.
 
similarity index 59%
rename from pdns/docs/markdown/authoritative/logging.md
rename to pdns/docs/markdown/common/logging.md
index 74a3716754d50c157cd9e8e2ef71a60fc08e747b..3b69d3480d7d985dd8123375611c7c3e5783b0e2 100644 (file)
@@ -1,11 +1,11 @@
 In a production environment, you will want to be able to monitor PDNS performance. Furthermore, PDNS can perform a configurable amount of operational logging. This chapter also explains how to configure syslog for best results.
 
 # Logging
-This chapter assumes familiarity with syslog, the unix logging device. PDNS logs messages with different levels. The more urgent the message, the lower the 'priority'. By default, PDNS will only log messages with an urgency of 3 or lower, but this can be changed using the [loglevel](settings.md#loglevel) setting in the configuration file. Setting it to 0 will eliminate all logging, 9 will log everything.
+This chapter assumes familiarity with syslog, the unix logging device. PDNS logs messages with different levels. The more urgent the message, the lower the 'priority'. By default, PDNS will only log messages with an urgency of 3 or lower, but this can be changed using the [loglevel](../authoritative/settings.md#loglevel) setting in the configuration file. Setting it to 0 will eliminate all logging, 9 will log everything.
 
 By default, logging is performed under the 'DAEMON' facility which is shared with lots of other programs. If you regard nameserving 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.
 
-For this purpose, syslog knows about 'local' facilities, numbered from LOCAL0 to LOCAL7. To move PDNS logging to LOCAL0, add [`logging-facility`](settings.md#logging-facility)`=0` to your configuration.
+For this purpose, syslog knows about 'local' facilities, numbered from LOCAL0 to LOCAL7. To move PDNS logging to LOCAL0, add [`logging-facility`](../authoritative/settings.md#logging-facility)`=0` to your configuration.
 
 Furthermore, you may want to have separate files for the differing priorities - preventing lower priority messages from obscuring important ones.
 
@@ -27,7 +27,7 @@ Be aware that syslog by default logs messages at the configured priority and hig
 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.
 
 ## Webserver
-To launch the internal webserver, add a [`webserver`](settings.md#webserver) statement to the `pdns.conf`. This will instruct the PDNS daemon to start a webserver on localhost at port 8081, without password protection. Only local users (on the same host) will be able to access the webserver by default. The webserver lists a lot of information about the PDNS process, including frequent queries, frequently failing queries, lists of remote hosts sending queries, hosts sending corrupt queries etc. The webserver does not allow remote management of the daemon. The following webserver related configuration items are available:
+To launch the internal webserver, add a [`webserver`](../authoritative/settings.md#webserver) statement to the `pdns.conf`. This will instruct the PDNS daemon to start a webserver on localhost at port 8081, without password protection. Only local users (on the same host) will be able to access the webserver by default. The webserver lists a lot of information about the PDNS process, including frequent queries, frequently failing queries, lists of remote hosts sending queries, hosts sending corrupt queries etc. The webserver does not allow remote management of the daemon. The following webserver related configuration items are available:
 
 * `webserver`: If set to anything but 'no', a webserver is launched.
 * `webserver-address`: Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the physical IP address of your nameserver.
@@ -133,46 +133,4 @@ Care has been taken to make the sending of statistics as unobtrusive as possible
 
 To benefit from our carbon/graphite support, either install Graphite, or use our own lightweight statistics daemon, Metronome, currently available on [GitHub](https://github.com/ahupowerdns/metronome/).
 
-Secondly, set [`carbon-server`](settings.md#carbon-server), possibly [`carbon-interval`](settings.md#carbon-interval) and possibly [`carbon-ourname`](settings.md#carbon-ourname) in the configuration.
-
-## Counters & variables
-A number of counters and variables are set during PDNS Authoritative Server operation.
-
-### Counters
-* **corrupt-packets**: Number of corrupt packets received
-* **latency**: Average number of microseconds a packet spends within PDNS
-* **packetcache-hit**: Number of packets which were answered out of the cache
-* **packetcache-miss**: Number of times a packet could not be answered out of the cache
-* **packetcache-size**: Amount of packets in the packetcache
-* **qsize-a**: Size of the queue before the transmitting socket.
-* **qsize-q**: Number of packets waiting for database attention
-* **servfail-packets**: Amount of packets that could not be answered due to database problems
-* **tcp-answers**: Number of answers sent out over TCP
-* **tcp-questions**: Number of questions received over TCP
-* **timedout-questions**: Amount of packets that were dropped because they had to wait too long internally
-* **udp-answers**: Number of answers sent out over UDP
-* **udp-questions**: Number of questions received over UDP
-
-### Ring buffers
-Besides counters, PDNS also maintains the ringbuffers. A ringbuffer records events, each new event gets a place in the buffer until it is full. When full, earlier entries get overwritten, hence the name 'ring'.
-
-By counting the entries in the buffer, statistics can be generated. These statistics can currently only be viewed using the webserver and are in fact not even collected without the webserver running.
-
-The following ringbuffers are available:
-
-* **logmessages**: All messages logged
-* **noerror-queries**: Queries for existing records but for a type we don't have.
-Queries for, say, the AAAA record of a domain, when only an A is available. Queries are listed in the following format: name/type. So an AAAA query for pdns.powerdns.com looks like pdns.powerdns.com/AAAA.
-* **nxdomain-queries**: Queries for non-existing records within existing domains.
-If PDNS knows it is authoritative over a domain, and it sees a question for a record in that domain that does not exist, it is able to send out an authoritative 'no such domain' message. Indicates that hosts are trying to connect to services really not in your zone.
-* **udp-queries**: All UDP queries seen.
-* **remotes**: Remote server IP addresses.
-Number of hosts querying PDNS. Be aware that UDP is anonymous - person A can send queries that appear to be coming from person B.
-* **remote-corrupts**: Remotes sending corrupt packets.
-Hosts sending PDNS broken packets, possibly meant to disrupt service. Be aware that UDP is anonymous - person A can send queries that appear to be coming from person B.
-* **remote-unauth**: Remotes querying domains for which we are not authoritative.
-It may happen that there are misconfigured hosts on the internet which are configured to think that a PDNS installation is in fact a resolving nameserver. These hosts will not get useful answers from PDNS. This buffer lists hosts sending queries for domains which PDNS does not know about.
-* **servfail-queries**: Queries that could not be answered due to backend errors.
-For one reason or another, a backend may be unable to extract answers for a certain domain from its storage. This may be due to a corrupt database or to inconsistent data. When this happens, PDNS sends out a 'servfail' packet indicating that it was unable to answer the question. This buffer shows which queries have been causing servfails.
-* **unauth-queries**: Queries for domains that we are not authoritative for.
-If a domain is delegated to a PDNS instance, but the backend is not made aware of this fact, questions come in for which no answer is available, nor is the authority. Use this ringbuffer to spot such queries.
+Secondly, set [`carbon-server`](../authoritative/settings.md#carbon-server), possibly [`carbon-interval`](../authoritative/settings.md#carbon-interval) and possibly [`carbon-ourname`](../authoritative/settings.md#carbon-ourname) in the configuration.
similarity index 70%
rename from pdns/docs/markdown/authoritative/security.md
rename to pdns/docs/markdown/common/security.md
index 4d2ba7987bd19d7e3419bee9f75be73752a6a86d..fa271945a21dda1f6c24b1dd216a4f4b197b0c45 100644 (file)
@@ -1,17 +1,17 @@
 # Security Settings
-PDNS has several options to easily allow it to run more securely. Most notable are the [`chroot`](settings.md#chroot), [`setuid`](settings.md#setuid) and [`setgid`](settings.md#setgid) options which can be specified.
+PDNS has several options to easily allow it to run more securely. Most notable are the [`chroot`](../authoritative/settings.md#chroot), [`setuid`](../authoritative/settings.md#setuid) and [`setgid`](../authoritative/settings.md#setgid) options which can be specified.
 
 For additional information on PowerDNS security, PowerDNS security incidents and PowerDNS security policy, see [our security policy](../security/index.md).
 
 ## Running as a less privileged identity
 
-By specifying [`setuid`](settings.md#setuid) and [`setgid`](settings.md#setgid), PDNS changes to this identity shortly after binding to the privileged DNS ports. These options are highly recommended. It is suggested that a separate identity is created for PDNS as the user 'nobody' is in fact quite powerful on most systems.
+By specifying [`setuid`](../authoritative/settings.md#setuid) and [`setgid`](../authoritative/settings.md#setgid), PDNS changes to this identity shortly after binding to the privileged DNS ports. These options are highly recommended. It is suggested that a separate identity is created for PDNS as the user 'nobody' is in fact quite powerful on most systems.
 
 Both these parameters can be specified either numerically or as real names. You should set these parameters immediately if they are not set!
 
 ## Jailing the process in a chroot
 
-The [`chroot`](settings.md#chroot) option secures PDNS to its own directory so that even if it should become compromised and under control of external influences, it will have a hard time affecting the rest of the system.
+The [`chroot`](../authoritative/settings.md#chroot) option secures PDNS to its own directory so that even if it should become compromised and under control of external influences, it will have a hard time affecting the rest of the system.
 
 Even though this will hamper hackers a lot, chroot jails have been known to be broken.
 
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..40da86c27b3b78d1363d59a0b24974b27ce099d4 100644 (file)
@@ -0,0 +1,68 @@
+# PowerDNS Recursor
+The PowerDNS recursor is part of the source tarball of the main PowerDNS distribution, but it is released separately. Starting from the version 3.0 pre-releases, there are zero known bugs or issues with the recursor. It is known to power the resolving needs of over 100 million internet connections.
+
+The documentation is only for the 3.0 series, users of older versions are urged to upgrade!
+
+## Notable features:
+-   Uses [MTasker](http://ds9a.nl/mtasker)
+-   Can handle thousands of concurrent questions. A quad Xeon 3GHz has been measured functioning very well at 40000 real life replayed packets per second, with 40% cpu idle. More testing equipment is needed to max out the recursor.
+-   Powered by a highly modern DNS packet parser that should be resistant against many forms of buffer overflows.
+-   Best spoofing protection that we know about, involving both source port randomisation and spoofing detection.
+-   Uses 'connected' UDP sockets which allow the recursor to react quickly to unreachable hosts or hosts for which the server is running, but the nameserver is down. This makes the recursor faster to respond in case of misconfigured domains, which are sadly very frequent.
+-   Special support for FreeBSD, Linux and Solaris stateful multiplexing (kqueue, epoll, completion ports, /dev/poll).
+-   Very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers.
+-   Code is written linearly, sequentially, which means that there are no problems with 'query restart' or anything.
+-   Relies heavily on Standard C++ Library infrastructure, which makes for little code (406 core lines).
+-   Is very verbose in showing how recursion actually works, when enabled to do so with --verbose.
+-   The algorithm is simple and quite nifty.
+
+The PowerDNS recursor is controlled and queried using the `rec_control` tool.
+
+## Configuration
+At startup, the recursing nameserver reads the file `recursor.conf` from the configuration directory, often `/etc/powerdns` or `/usr/local/etc`. Each setting can appear on the command line, prefixed by '--', or in the configuration file. The command line overrides the configuration file.
+
+A switch can be set to on simply by passing it, like '--daemon', and turned off explicitly by '--daemon=off' or '--daemon=no'.
+
+All settings can be found [here](settings.md)
+2. pdns\_recursor command line
+
+[Prev](built-in-recursor.html) 
+
+Chapter 18. PowerDNS Recursor: a high performance resolving nameserver
+
+ [Next](rec-control.html)
+
+* * * * *
+
+2. pdns\_recursor command line
+------------------------------
+
+All configuration settings from the previous section can also be passed on the command line, and will override the configuration file. In addition, the following options make sense on the command line:
+
+--config  
+Emit a default configuration file.
+
+--help  
+Output all configuration settings and command line flags.
+
+* * * * *
+
+<table>
+<colgroup>
+<col width="33%" />
+<col width="33%" />
+<col width="33%" />
+</colgroup>
+<tbody>
+<tr class="odd">
+<td align="left"><a href="built-in-recursor.html">Prev</a> 
+<a href="built-in-recursor.html">Up</a>
+ <a href="rec-control.html">Next</a></td>
+<td align="left">Chapter 18. PowerDNS Recursor: a high performance resolving nameserver 
+<a href="index.html">Home</a>
+ 3. Controlling and querying the recursor</td>
+</tr>
+</tbody>
+</table>
+
+
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..70dd41ebde331ab02c87881da2257e7fba7da9fb 100644 (file)
@@ -0,0 +1,59 @@
+# PowerDNS Recursor performance
+To get the best out of the PowerDNS recursor, which is important if you are doing thousands of queries per second, please consider the following.
+
+-   Limit the size of the caches to a sensible value. Cache hit rate does not improve meaningfully beyond 4 million **max-cache-entries** per thread, reducing the memory footprint reduces CPU cache misses. See below for more information about the various caches.
+-   Compile using g++ 4.1 or later. This compiler really does a good job on PowerDNS, much better than 3.4 or 4.0.
+-   On AMD/Intel hardware, wherever possible, run a 64-bit binary. This delivers a nearly twofold performance increase. On UltraSPARC, there is no need to run with 64 bits.
+-   Consider performing a 'profiled build' as described in the README. This is good for a 20% performance boost in some cases.
+-   When running with \>3000 queries per second, and running Linux versions prior to 2.6.17 on some motherboards, your computer may spend an inordinate amount of time working around an ACPI bug for each call to gettimeofday. This is solved by rebooting with 'clock=tsc' or upgrading to a 2.6.17 kernel.
+
+    The above is relevant if dmesg shows **Using pmtmr for high-res timesource**
+
+-   A busy server may need hundreds of file descriptors on startup, and deals with spikes better if it has that many available later on. Linux by default restricts processes to 1024 file descriptors, which should suffice most of the time, but Solaris has a default limit of 256. This can be raised using the ulimit command. FreeBSD has a default limit that is high enough for even very heavy duty use.
+-   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'.
+-   For older versions \<3.2: If you need it, try **--fork**, this will fork the daemon into two halves, allowing it to benefit from a second CPU. This feature almost doubles performance, but is a bit of a hack.
+-   for 3.2 and higher, set 'threads' to your number of CPUs.
+-   For best PowerDNS Recursor performance, use a recent version of your operating system, since this generally offers the best event multiplexer implementation available (kqueue, epoll, ports or /dev/poll).
+-   A Recursor under high load puts a severe stress on any stateful (connection tracking) firewall, so much so that the firewall may fail.
+
+    Specifically, many Linux distributions run with a connection tracking firewall configured. For high load operation (thousands of queries/second), It is advised to either turn off iptables completely, or use the 'NOTRACK' feature to make sure DNS traffic bypasses the connection tracking.
+
+    Sample Linux command lines would be:
+
+```
+# iptables -t raw -I OUTPUT -p udp --dport 53 -j NOTRACK
+# iptables -t raw -I OUTPUT -p udp --sport 53 -j NOTRACK
+# iptables -t raw -I PREROUTING -p udp --dport 53 -j NOTRACK
+# iptables -t raw -I PREROUTING -p udp --sport 53 -j NOTRACK
+# iptables -I INPUT -p udp --dport 53 -j ACCEPT
+# iptables -I INPUT -p udp --sport 53 -j ACCEPT
+# iptables -I OUTPUT -p udp --dport 53 -j ACCEPT
+
+    # # optionally
+# ip6tables -t raw -I OUTPUT -p udp --dport 53 -j NOTRACK
+# ip6tables -t raw -I OUTPUT -p udp --sport 53 -j NOTRACK
+# ip6tables -t raw -I PREROUTING -p udp --sport 53 -j NOTRACK
+# ip6tables -t raw -I PREROUTING -p udp --dport 53 -j NOTRACK
+# ip6tables -I INPUT -p udp --dport 53 -j ACCEPT
+# ip6tables -I INPUT -p udp --sport 53 -j ACCEPT
+# ip6tables -I OUTPUT -p udp --dport 53 -j ACCEPT
+```
+
+Following the instructions above, you should be able to attain very high query rates.
+
+## Recursor Caches
+The PowerDNS Recursor contains a number of caches, or information stores:
+
+### Nameserver speeds cache
+The "NSSpeeds" cache contains the average latency to all remote authoritative servers.
+
+### Negative cache
+The "Negcache" contains all domains known not to exist, or record types not to exist for a domain.
+
+### Recursor Cache
+The Recursor Cache contains all DNS knowledge gathered over time.
+
+### Packet Cache
+The Packet Cache contains previous answers sent to clients. If a question comes in that matches a previous answer, this is sent back directly.
+
+The Packet Cache is consulted first, immediately after receiving a packet. This means that a high hitrate for the Packet Cache automatically lowers the cache hitrate of subsequent caches. This explains why releases 3.2 and beyond see dramatically lower DNS cache hitrates, since this is the first version with a Packet Cache.
diff --git a/pdns/docs/markdown/recursor/running.md b/pdns/docs/markdown/recursor/running.md
new file mode 100644 (file)
index 0000000..69fa537
--- /dev/null
@@ -0,0 +1,65 @@
+# Controlling and querying the recursor
+To control and query the PowerDNS recursor, the tool `rec_control` is provided. This program talks to the recursor over the 'controlsocket', often stored in `/var/run`.
+
+As a sample command, try:
+
+``` {.screen}
+      # rec_control ping
+      pong
+```
+
+When not running as root, `--socket-dir=/tmp` might be appropriate.
+
+## `rec_control` commands
+dump-cache filename  
+Dumps the entire cache to the filename mentioned. This file should not exist already, PowerDNS will refuse to overwrite it. While dumping, the recursor will not answer questions.
+
+get ### `statistic`
+Retrieve a statistic. For items that can be queried, see below.
+
+### `get-all`
+Retrieve all statistics in one go. Available since version 3.2.
+
+get-parameter parameter1 parameter2 ### `..`
+Retrieve a configuration parameter. All parameters from the configuration and command line can be queried. Available since version 3.2.
+
+### `ping`
+Check if server is alive.
+
+### `quit`
+Request shutdown of the recursor.
+
+### `reload-acls`
+Reload access control lists.
+
+### `reload-zones`
+Reload data about all authoritative and forward zones. The configuration file is also scanned to see if the **auth-domain**, **forward-domain** and **export-etc-hosts** statements have changed, and if so, these changes are incorporated.
+
+### `set-minimum-ttl`
+Available since 3.6, this setting artificially raises all TTLs to be at least this long. While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. Corresponds to the configuration file setting 'minimum-ttl-override'.
+
+### `top-remotes`
+Shows the top-20 most active remote hosts. Statistics are over the last 'remotes-ringbuffer-entries' queries, which defaults to 0.
+
+### `trace-regex regex`
+Available since 3.5.
+
+Queries matching this regular expression will generate voluminous tracing output. Be aware that matches from the packet cache will still not generate tracing. To unset the regex, pass 'trace-regex' without a new regex.
+
+The regular expression is matched against domain queries terminated with a '.'. So, for example the regex 'powerdns.com\$' will not match a query for 'www.powerdns.com', since the attempted match will be with 'www.powerdns.com.'.
+
+In addition, since this is a regular expression, to exclusively match queries for 'www.powerdns.com', one should escape the dots: '\^www\\.powerdns\\.com\\.\$'.
+
+Multiple matches can be chained with the | operator. For example, to match all queries for Dutch (.nl) and German (.de) domain names, use: '\\.nl\\.\$|\\.de\\.\$'.
+
+### `wipe-cache domain0. [domain1. domain2.]`
+Wipe entries from the cache. This is useful if, for example, an important server has a new IP address, but the TTL has not yet expired. Multiple domain names can be passed. For versions before 3.1, you must terminate a domain with a .! So to wipe powerdns.org, issue 'rec\_control wipe-cache powerdns.org.'. For later versions, the dot is optional.
+
+Note that deletion is exact, wiping 'com.' will leave 'www.powerdns.com.' untouched!
+
+**Warning**: As of 3.1.7, this command also wipes the negative query cache for the specified domain.
+**Warning**: Don't just wipe 'www.somedomain.com', its NS records or CNAME target may still be undesired, so wipe 'somedomain.com' as well.
+
+The command 'get' can query a large number of statistics, which are detailed in [Performance Monitoring](stats.md).
+
+More details on what 'throttled' queries and the like are can be found below in [Security Settings](security.md).
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..5b12a19329ad04f051bd3e9ced6a11b92b9eeaeb 100644 (file)
@@ -0,0 +1,103 @@
+# Scripting The Recursor
+As of version 3.1.7 of the PowerDNS Recursor, it is possible to modify resolving behaviour using simple scripts written in the [Lua](http://www.lua.org) programming language.
+
+These scripts can be used to quickly override dangerous domains, fix things that are wrong, for load balancing or for legal or commercial purposes.
+
+As of 3.1.7, queries can be intercepted in two places: before the resolving logic starts to work, plus after the resolving process failed to find a correct answer for a domain.
+
+## Configuring Lua scripts
+In order to load scripts, the PowerDNS Recursor must have Lua support built in. The packages distributed from the PowerDNS website have this language enabled, other distributions may differ. To compile with Lua support, use: `LUA=1 make` or `LUA=1 gmake` as the case may be. Paths to the Lua include files and binaries may be found near the top of the `Makefile`.
+
+If Lua support is available, a script can be configured either via the configuration file, or at runtime via the `rec_control` tool. Scripts can be reloaded or unloaded at runtime with no interruption in operations. If a new script contains syntax errors, the old script remains in force.
+
+On the command line, or in the configuration file, the setting `lua-dns-script` can be used to supply a full path to a 'lua' script.
+
+At runtime, `rec_control reload-lua-script` can be used to either reload the script from its current location, or, when passed a new file name, load one from a new location. A failure to parse the new script will leave the old script in working order.
+
+Finally, `rec_control unload-lua-script` can be used to remove the currently installed script, and revert to unmodified behaviour.
+
+## Writing Lua PowerDNS Recursor scripts
+Once a script is loaded, PowerDNS looks for several functions, as detailed below. All of these functions are optional.
+
+### `preresolve ( remoteip, domain, qtype )`
+is called before any DNS resolution is attempted, and if this function indicates it, it can supply a direct answer to the DNS query, overriding the internet. This is useful to combat botnets, or to disable domains unacceptable to an organization for whatever reason.
+
+### `postresolve ( remoteip, domain, qtype, records, origrcode )`
+is called right before returning a response to a client (and, unless `setvariable()` is called, to the packet cache too). It allows inspection and modification of almost any detail in the return packet. Available since version 3.4.
+
+### `function nxdomain ( remoteip, domain, qtype )`
+is called after the DNS resolution process has run its course, but ended in an 'NXDOMAIN' situation, indicating that the domain or the specific record does not exist. This can be used for various purposes.
+
+### `function nodata ( remoteip, domain, qtype, records )`
+is just like `nxdomain`, except it gets called when a domain exists, but the requested type does not. This is where one would implement DNS64. Available since version 3.4.
+
+All these functions are passed the IP address of the requester, plus the name and type being requested. In return, these functions indicate if they have taken over the request, or want to let normal proceedings take their course.
+
+**Warning**: In development versions of the PowerDNS Recursor, versions which were never released except as for testing purposes, these functions had a fourth parameter: localip This parameter has been replaced by `getlocaladdress()`, for which see below.
+
+If a function has taken over a request, it should return an rcode (usually 0), and specify a table with records to be put in the answer section of a packet. An interesting rcode is NXDOMAIN (3, or `pdns.NXDOMAIN`), which specifies the non-existence of a domain. Returning -1 and an empty table signifies that the function chose not to intervene.
+
+A minimal sample script:
+
+```
+function nxdomain ( ip, domain, qtype )
+  print ("nxhandler called for: ", ip, domain, qtype)
+
+  ret={}
+  if qtype ~= pdns.A then return pdns.PASS, ret end  --  only A records
+  if not string.find(domain, "^www%.") then return pdns.PASS, ret end  -- only things that start with www.
+  if not matchnetmask(ip, "10.0.0.0/8", "192.168.0.0/16")  then return pdns.PASS, ret end -- only interfere with local queries
+  ret[1]={qtype=pdns.A, content="192.0.2.13"}    -- add IN A 192.0.2.13
+  ret[2]={qtype=pdns.A, content="192.0.2.21"}    -- add IN A 192.0.2.21
+  setvariable()
+  return 0, ret                 -- return no error, plus records
+end
+```
+
+**Warning**: Please do NOT use the above sample script in production! Responsible NXDomain redirection requires more attention to detail.
+
+Note that the domain is passed to the Lua function terminated by a '.'. A more complete sample script is provided as `powerdns-example-script.lua` in the PowerDNS Recursor distribution.
+
+The answer content format is (nearly) identical to the storage in the PowerDNS Authoritative Server database, or as in zone files. The exception is that, unlike in the database, there is no 'prio' field, which means that an MX record with priority 25 pointing to 'smtp.example.net' would be encoded as '25 smtp.example.net.'.
+
+Useful return 'rcodes' include 0 for "no error", `pdns.NXDOMAIN` for "NXDOMAIN", `pdns.DROP` to drop the question from further processing (since 3.6, and such a drop is accounted in the 'policy-drops' metric).
+
+Fields that can be set in the return table include:
+
+* content: Content of the record, as specified above in 'zone file format'. No default, mandatory field.
+* place: Place of this record. Defaults to 1, indicating 'Answer' section. Can also be 2, for Authority of 3 for Additional. When using this rare feature, always emit records with 'Place' in ascending order. This field is usually not needed.
+* qname: qname of the answer, the 'name' of the record. Defaults to the name of the query, which is almost always correct except when specifying additional records or rolling out a CNAME chain.
+* qtype: Currently the numerical qtype of the answer, defaulting to '1' which is an A record. Can be also be specified as `pdns.A`, or `pdns.CNAME` etc.
+* ttl: Time to live of a record. Defaults to 3600. Be sure not to specify differing TTLs within answers with an identical qname. While this will be encoded in DNS, actual results may be undesired.
+* qclass: Query-Class of a record. Defaults to 1 (IN). Be sure to always return the correct qclass in each record! Valid query-classes are 1 (IN), 3 (CHAOS), 254 (NONE) and 255 (ANY).
+
+**Warning**: Only the IN class (1) is fully supported!
+**Warning**: The result table must have indexes that start at 1! Otherwise the first or confusingly the last entry of the table will be ignored. A useful technique is to return data using: `return 0, {{qtype=1, content="192.0.2.4"}, {qtype=1, content="4.3.2.1"}}` as this will get the numbering right automatically.
+
+The function `matchnetmask(ip, netmask1, netmask2..)` (or `matchnetmask(ip, {netmask1, netmask2})`) is available to match incoming queries against a number of netmasks. If any of these match, the function returns true.
+
+To log messages with the main PowerDNS Recursor process, use `pdnslog(message)`. Available since version 3.2. pdnslog can also write out to a syslog loglevel if specified. Use `pdnslog(message, pdns.loglevels.LEVEL)` with the correct pdns.loglevels entry. Entries are listed in the following table:
+
+| | |
+|:--||:--|
+|All|pdns.loglevels.All|
+|NTLog|pdns.loglevels.NTLog|
+|Alert|pdns.loglevels.Alert|
+|Critical|pdns.loglevels.Critical|
+|Error|pdns.loglevels.Error|
+|Warning|pdns.loglevels.Warning|
+|Notice|pdns.loglevels.Notice|
+|Info|pdns.loglevels.Info|
+|Debug|pdns.loglevels.Debug|
+|None|pdns.loglevels.None|
+
+`pdnslog(message)` will write out to Info by default.
+
+To retrieve the IP address on which a query was received, use `getlocaladdress()`. Available since version 3.2.
+
+To indicate that an answer should not be cached in the packet cache, use `setvariable()`. Available since version 3.3.
+
+To get fake AAAA records for DNS64 usage, use `return "getFakeAAAARecords", domain, "fe80::21b:77ff:0:0"`. Available since version 3.4.
+
+## CNAME chain resolution
+It may be useful to return a CNAME record for Lua, and then have the PowerDNS Recursor continue resolving that CNAME. This can be achieved by returning: "followCNAMERecords", 0, {{qtype=pdns.CNAME, content="www.powerdns.com"}}. This indicates an rcode of 0 and the records to put in the record. But the first string instruct PowerDNS to complete the CNAME chain. Available since 3.6.
diff --git a/pdns/docs/markdown/recursor/security.md b/pdns/docs/markdown/recursor/security.md
new file mode 100644 (file)
index 0000000..4c0041c
--- /dev/null
@@ -0,0 +1,19 @@
+# Security Measures in the Recursor
+
+## Anti-spoofing
+The PowerDNS recursor 3.0 uses a fresh UDP source port for each outgoing query, making spoofing around 64000 times harder. This raises the bar from 'easily doable given some time' to 'very hard'. Under some circumstances, 'some time' has been measured at 2 seconds. This technique was first used by `dnscache` by Dan J. Bernstein.
+
+In addition, PowerDNS detects when it is being sent too many unexpected answers, and mistrusts a proper answer if found within a clutch of unexpected ones.
+
+This behaviour can be tuned using the **spoof-nearmiss-max**.
+
+## Throttling
+PowerDNS implements a very simple but effective nameserver. Care has been taken not to overload remote servers in case of overly active clients.
+
+This is implemented using the 'throttle'. This accounts all recent traffic and prevents queries that have been sent out recently from going out again.
+
+There are three levels of throttling.
+
+-   If a remote server indicates that it is lame for a zone, the exact question won't be repeated in the next 60 seconds.
+-   After 4 ServFail responses in 60 seconds, the query gets throttled too.
+-   5 timeouts in 20 seconds also lead to query suppression.
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..343625571d3ecaa4d07e703b22871b1948460eaa 100644 (file)
@@ -0,0 +1,180 @@
+# All PowerDNS Recursor Settings
+Each setting can appear on the command line, prefixed by '--', or in the configuration file. The command line overrides the configuration file.
+
+## `aaaa-additional-processing`
+If turned on, the recursor will attempt to add AAAA IPv6 records to questions for MX records and NS records. Can be quite slow as absence of these records in earlier answers does not guarantee their non-existence. Can double the amount of queries needed. Off by default.
+
+## `allow-from`
+Comma separated netmasks (both IPv4 and IPv6) that are allowed to use the server. The default allows access only from RFC 1918 private IP addresses, like 10.0.0.0/8. Due to the aggressive nature of the internet these days, it is highly recommended to not open up the recursor for the entire internet. Questions from IP addresses not listed here are ignored and do not get an answer.
+
+## `allow-from-file`
+Like [`allow-from`](#allow-from), except reading from file. Overrides the [`allow-from`](#allow-from) setting. To use this feature, supply one netmask per line, with optional comments preceded by a \#. Available since version 3.1.5.
+
+## `any-to-tcp`
+Answer questions for the ANY type on UDP with a truncated packet that refers the remote server to TCP. Useful for mitigating ANY reflection attacks. Defaults to off.
+
+## `auth-can-lower-ttl`
+Authoritative zones can transmit a TTL value that is lower than that specified in the parent zone. This is called a 'delegation inconsistency'. To follow RFC 2181 paragraphs 5.2 and 5.4 to the letter, enable this feature. This will mean a slight deterioration of performance, and it will not solve any problems, but does make the recursor more standards compliant. Not recommended unless you have to tick an 'RFC 2181 compliant' box. Off by default.
+
+## `auth-zones`
+Comma separated list of 'zonename=filename' pairs. Zones read from these files (in BIND format) are served authoritatively. Example: `auth-zones=example.org=/var/zones/example.org, powerdns.com=/var/zones/powerdns.com`. Available since version 3.1.
+
+## `carbon-ourname`
+If sending carbon updates, if set, this will override our hostname. See [XXX](XXX). Available beyond 3.5.3.
+
+## `carbon-server=...`
+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 [XXX](XXX). Available beyond 3.5.3.
+
+## `carbon-interval=...`
+If sending carbon updates, this is the interval between them in seconds. See [XXX](XXX). Available beyond 3.5.3.
+
+## `chroot`
+If set, chroot to this directory for more security. See [XXX](XXX).
+
+Make sure that `/dev/log` is available from within the chroot. Logging will silently fail over time otherwise (on logrotate).
+
+## `client-tcp-timeout`
+Time to wait for data from TCP clients. Defaults to 2 seconds.
+
+## `config-dir`
+Directory where the configuration file can be found.
+
+## `daemon`
+Operate in the background, which is the default.
+
+## `delegation-only`
+A Verisign special.
+
+## `disable-packetcache`
+Turn off the packet cache. Useful when running with Lua scripts that can not be cached. Available since version 3.2.
+
+## `dont-query`
+The DNS is a public database, but sometimes contains delegations to private IP addresses, like for example 127.0.0.1. This can have odd effects, depending on your network, and may even be a security risk. Therefore, since version 3.1.5, the PowerDNS recursor by default does not query private space IP addresses. This setting can be used to expand or reduce the limitations.
+
+## `entropy-source`
+From version 3.1.5 onwards, PowerDNS can read entropy from a (hardware) source. This is used for generating random numbers which are very hard to predict. Generally on UNIX platforms, this source will be `/dev/urandom`, which will always supply random numbers, even if entropy is lacking. Change to `/dev/random` if PowerDNS should block waiting for enough entropy to arrive.
+
+## `export-etc-hosts`
+If set, this flag will export the host names and IP addresses mentioned in `/etc/hosts`. Available since version 3.1.
+
+## `export-etc-hosts-search-suffix`
+If set, all hostnames in the export-etc-hosts file are loaded in canonical form, based on this suffix, unless the name contain a '.', in which case the name is unchanged. So an entry called 'pc' with export-etc-hosts-search-suffix='home.com' will lead to the generation of 'pc.home.com' within the recursor. An entry called 'server1.home' will be stored as 'server1.home', regardless of the export-etc-hosts setting. Available in since version 3.4.
+
+## `fork`
+If running on an SMP system with enough memory, this feature forks PowerDNS so it benefits from two processors. Experimental. Renames controlsockets, so care is needed to connect to the right one using `rec_control`, using `socket-pid`. Available in versions of the Recursor before 3.2, replaced by the 'threads' setting.
+
+## `forward-zones`
+Comma separated list of 'zonename=IP' pairs. Queries for zones listed here will be forwarded to the IP address listed. `forward-zones=example.org=203.0.113.210, powerdns.com=127.0.0.1`. Available since version 3.1.
+
+Since version 3.1.5, multiple IP addresses can be specified. Additionally, port numbers other than 53 can be configured. Sample syntax: `forward-zones=example.org=203.0.113.210:5300;127.0.0.1, powerdns.com=127.0.0.1;198.51.100.10:530`, or on the command line: `--forward-zones="example.org=203.0.113.210:5300;127.0.0.1, powerdns.com=127.0.0.1;9.8.7.6:530"`,
+
+Forwarded queries have the 'recursion desired' bit set to 0, meaning that this setting is intended to forward queries to authoritative servers.
+
+## `forward-zones-file`
+Same as [`forward-zones`](#forward-zones-file), parsed from a file. Only 1 zone is allowed per line, specified as follows: `example.org=203.0.113.210, 192.0.2.4:5300`. No comments are allowed. Available since version 3.1.5.
+
+Since version 3.2, zones prefixed with a '+' are forwarded with the recursion-desired bit set to one, for which see 'forward-zones-recurse'. Default behaviour without '+' is as with [`forward-zones`](#forward-zones).
+
+## `forward-zones-recurse`
+Like regular 'forward-zones' (see above), but forwarded queries have the 'recursion desired' bit set to 1, meaning that this setting is intended to forward queries to authoritative servers or to resolving servers. Available since version 3.2.
+
+## `hint-file`
+If set, the root-hints are read from this file. If unset, default root hints are used. Available since version 2.9.19.
+
+## `latency-statistic-size`
+Indication of how many queries will be averaged to get the average latency reported by the 'qa-latency' metric. Since 3.6.
+
+## `local-address`
+Local IPv4 or IPv6 addresses to bind to, comma separated. Defaults to only loopback. Addresses can also contain port numbers, for IPv4 specify like this: `192.0.2.4:5300`, for IPv6: `[::1]:5300`. Port specifications are available since version 3.1.2.
+
+**Warning**: When binding to wildcard addresses, UNIX semantics mean that answers may not be sent from the address a query was received on. It is highly recommended to bind to explicit addresses.
+
+## `local-port`
+Local port (singular) to bind to. Defaults to 53.
+
+## `loglevel`
+Amount of logging. Higher is more, more logging may destroy performance. Available since 3.6.
+
+## `log-common-errors`
+Some DNS errors occur rather frequently and are no cause for alarm. Logging these is on by default.
+
+## `logging-facility`
+If set to a digit, logging is performed under this LOCAL facility. See [Logging](../common/logging.md#logging). Available from 3.1.3 and onwards. Do not pass names like 'local0'!
+
+## `max-cache-entries`
+Maximum number of DNS cache entries. 1 million per thread will generally suffice for most installations.
+
+## `max-packetcache-entries`
+Maximum number of Packet Cache entries. 1 million per thread will generally suffice for most installations. Available since version 3.2.
+
+## `max-cache-ttl`
+Maximum number of seconds to cache an item in the DNS cache, no matter what the original TTL specified. Available since version 3.2.
+
+## `max-negative-ttl`
+A query for which there is authoritatively no answer is cached to quickly deny a record's existence later on, without putting a heavy load on the remote server. In practice, caches can become saturated with hundreds of thousands of hosts which are tried only once. This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative entries are cached.
+
+## `max-tcp-clients`
+Maximum number of simultaneous incoming TCP connections allowed. Defaults to 128. Available since version 2.9.18.
+
+## `max-tcp-per-client`
+Maximum number of simultaneous incoming TCP connections allowed per client (remote IP address). Defaults to 0, which means unlimited.
+
+## `minimum-ttl-override`
+Available since 3.6, this setting artificially raises all TTLs to be at least this long. While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. Can be set at runtime using `rec_control set-minimum-ttl 3600`. To disable, set to 0 (the default).
+
+## `network-timeout`
+Number of milliseconds to wait for a remote authoritative server to respond. Defaults to 1500 msec, available since version 3.2.
+
+## `packetcache-ttl`
+Maximum number of seconds to cache an item in the packet cache, no matter what the original TTL specified. Available since version 3.2.
+
+## `packetcache-servfail-ttl`
+Maximum number of seconds to cache a 'server failure' answer in the packet cache. Available since version 3.2.
+
+## `pdns-distributes-queries`
+If set, PowerDNS will have only 1 thread listening on client sockets, and distribute work by itself over threads. Improves performance on Linux. Do not use on Recursor versions before 3.6 as the feature was experimental back then, and not that stable.
+
+## `query-local-address`
+Send out local queries from this address, or addresses. Since version 3.2, by adding multiple addresses, increased spoofing resilience is achieved. Addresses can be separated by a comma.
+
+## `query-local-address6`
+Send out local IPv6 queries from this address or addresses. Disabled by default, which also disables outgoing IPv6 support. Since version 3.2, multiple addresses can be specified, separated by a comma.
+
+## `quiet`
+Don't log queries. On by default.
+
+## `remotes-ringbuffer-entries`
+Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. Can be read out using **rec\_control top-remotes**. Defaults to 0.
+
+## `serve-rfc*1918*`
+On by default, this makes the server authoritatively aware of: `10.in-addr.arpa`, `168.192.in-addr.arpa`, `16-31.172.in-addr.arpa`, which saves load on the AS112 servers. Individual parts of these zones can still be loaded or forwarded.
+
+## `server-down-max-fails`, `server-down-throttle-time`
+If a server has not responded in any way this many times in a row, no longer send it any queries for server-down-throttle-time seconds. Afterwards, we will try a new packet, and if that also gets no response at all, we again throttle for server-down-throttle-time-seconds. Even a single response packet will drop the block. Available and on by default since 3.6.
+
+## `server-id`
+The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. Use this setting to override the answer it gives.
+
+setgid, setuid  
+PowerDNS can change its user and group id after binding to its socket. Can be used for better security.
+
+## `socket-dir`
+Where to store the control socket. This option also works with the controller, **rec\_control**.
+
+## `socket-owner`, `socket-group`, `socket-mode`
+Owner, group and mode of the controlsocket. Owner and group can be specified by name, mode is in octal.
+
+## `spoof-nearmiss-max`
+If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. Defaults to 20.
+
+## `trace`
+If turned on, output impressive heaps of logging. May destroy performance under load.
+
+## `udp-truncation-threshold=...`
+EDNS0 allows for large UDP response datagrams, which can potentially raise performance. Large responses however also have downsides in terms of reflection attacks. This setting limits the accepted size. Maximum value is 65535, but values above 4096 should probably not be attempted. Default is 1680.
+
+## `version`
+Print version of this binary. Useful for checking which version of the PowerDNS recursor is installed on a system. Available since version 3.1.5.
+
+## `version-string`
+By default, PowerDNS replies to the 'version.bind' query with its version number. Security conscious users may wish to override the reply PowerDNS issues.
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..27f928fe424a93fde4b10b50496cb905a406b67f 100644 (file)
@@ -0,0 +1,70 @@
+# Recursor Statistics
+The `rec_control get` command can be used to query the following statistics, either single keys or multiple statistics at once:
+
+```
+all-outqueries      counts the number of outgoing UDP queries since starting
+answers0-1          counts the number of queries answered within 1 millisecond
+answers100-1000     counts the number of queries answered within 1 second
+answers10-100       counts the number of queries answered within 100 milliseconds
+answers1-10         counts the number of queries answered within 10 milliseconds
+answers-slow        counts the number of queries answered after 1 second
+cache-bytes         Size of the cache in bytes (since 3.3.1)
+cache-entries       shows the number of entries in the cache
+cache-hits          counts the number of cache hits since starting
+cache-misses        counts the number of cache misses since starting
+chain-resends       number of queries chained to existing outstanding query
+client-parse-errors counts number of client packets that could not be parsed
+concurrent-queries  shows the number of MThreads currently running
+dlg-only-drops      number of records dropped because of delegation only setting
+dont-outqueries     number of outgoing queries dropped because of 'dont-query' setting (since 3.3)
+ipv6-outqueries     number of outgoing queries over IPv6
+max-mthread-stack   maximum amount of thread stack ever used
+negcache-entries    shows the number of entries in the Negative answer cache
+noerror-answers     counts the number of times it answered NOERROR since starting
+nsspeeds-entries    shows the number of entries in the NS speeds map
+nsset-invalidations number of times an nsset was dropped because it no longer worked
+nxdomain-answers    counts the number of times it answered NXDOMAIN since starting
+outgoing-timeouts   counts the number of timeouts on outgoing UDP queries since starting
+over-capacity-drops Questions dropped because over maximum concurrent query limit (since 3.2)
+packetcache-bytes   Size of the packet cache in bytes (since 3.3.1)
+packetcache-entries Size of packet cache (since 3.2)
+packetcache-hits    Packet cache hits (since 3.2)
+packetcache-misses  Packet cache misses (since 3.2)
+policy-drops        Packets dropped because of (Lua) policy decision
+qa-latency          shows the current latency average, in microseconds
+questions           counts all End-user initiated queries with the RD bit set
+ipv6-questions      counts all End-user initiated queries with the RD bit set, received over IPv6 UDP
+resource-limits     counts number of queries that could not be performed because of resource limits
+server-parse-errors counts number of server replied packets that could not be parsed
+servfail-answers    counts the number of times it answered SERVFAIL since starting
+spoof-prevents      number of times PowerDNS considered itself spoofed, and dropped the data
+sys-msec            number of CPU milliseconds spent in 'system' mode
+tcp-client-overflow number of times an IP address was denied TCP access because it already had too many connections
+tcp-outqueries      counts the number of outgoing TCP queries since starting
+tcp-questions       counts all incoming TCP queries (since starting)
+throttled-out       counts the number of throttled outgoing UDP queries since starting
+throttle-entries    shows the number of entries in the throttle map
+unauthorized-tcp    number of TCP questions denied because of allow-from restrictions
+unauthorized-udp    number of UDP questions denied because of allow-from restrictions 
+unexpected-packets  number of answers from remote servers that were unexpected (might point to spoofing)
+uptime              number of seconds process has been running (since 3.1.5)
+user-msec           number of CPU milliseconds spent in 'user' mode
+```
+
+In the `rrd/` subdirectory a number of rrdtool scripts is provided to make nice graphs of all these numbers. Use **rec\_control get-all** to get all statistics in one go.
+
+It should be noted that answers0-1 + answers1-10 + answers10-100 + answers100-1000 + packetcache-hits + over-capacity-drops + policy-drops = questions.
+
+Also note that unauthorized-tcp and unauthorized-udp packets do not end up in the 'questions' count.
+
+Every half our or so, the recursor outputs a line with statistics. More infrastructure is planned so as to allow for Cricket or MRTG graphs. To force the output of statistics, send the process a SIGUSR1. A line of statistics looks like this:
+
+```
+Feb 10 14:16:03 stats: 125784 questions, 13971 cache entries, 309 negative entries, 84% cache hits, outpacket/query ratio 37%, 12% throttled
+```
+
+This means that there are 13791 different names cached, which each may have multiple records attached to them. There are 309 items in the negative cache, items of which it is known that don't exist and won't do so for the near future. 84% of incoming questions could be answered without any additional queries going out to the net.
+
+The outpacket/query ratio means that on average, 0.37 packets were needed to answer a question. Initially this ratio may be well over 100% as additional queries may be needed to actually recurse the DNS and figure out the addresses of nameservers.
+
+Finally, 12% of queries were not performed because identical queries had gone out previously, saving load servers worldwide.
index d99f2bc9953dc0bbbc547dc386be0b09d8f7fd75..72b16a34b3a583c8759aced4a5bcaef7baffafa0 100644 (file)
@@ -7,15 +7,15 @@ pages:
   - [index.md, 'PowerDNS Server', 'Introduction']
   - [changelog.md, 'PowerDNS Server', 'Changelogs']
   - [types.md, 'PowerDNS Server', 'Supported DNS Record Types']
+  - [common/logging.md, 'PowerDNS Server', 'Logging and Performance Monitoring']
+  - [common/security.md, 'PowerDNS Server', 'Security settings & considerations']
   - [authoritative/index.md, 'Authoritative', 'Introduction']
   - [authoritative/installation.md, 'Authoritative', 'Installing and Running']
   - [authoritative/upgrading.md, 'Authoritative', 'Upgrading']
   - [authoritative/modes-of-operation.md, 'Authoritative', 'Modes of Operation']
   - [authoritative/virtual.md, 'Authoritative', 'Virtual Hosting']
   - [authoritative/fancy-records.md, 'Authoritative', 'Fancy Records']
-  - [authoritative/performance.md, 'Authoritative', 'Performance Tuning']
-  - [authoritative/logging.md, 'Authoritative', 'Logging and Performance Monitoring']
-  - [authoritative/security.md, 'Authoritative', 'Security settings & considerations']
+  - [authoritative/performance.md, 'Authoritative', 'Performance Tuning and Monitoring']
   - [authoritative/migration.md, 'Authoritative', 'Migrating to PowerDNS']
   - [authoritative/recursion.md, 'Authoritative', 'Recursion with the Authoritative Server']
   - [authoritative/dnssec.md, 'Authoritative', 'Serve DNSSEC Signed Data']
@@ -28,8 +28,8 @@ pages:
   - [authoritative/backend-tinydns.md, 'Authoritative', 'Backend: TinyDNS']
   - [authoritative/settings.md, 'Authoritative', 'List of Settings']
   - [recursor/index.md, 'Recursor', 'Introduction']
-  - [recursor/anti-spoofing.md, 'Recursor', 'Anti-Spoofing']
-  - [recursor/stats.md, 'Recursor', 'Statistics']
+  - [recursor/security.md, 'Recursor', 'Security of the Recursor']
+  - [recursor/stats.md, 'Recursor', 'Recursor Statistics']
   - [recursor/performance.md, 'Recursor', 'Performance Tuning']
   - [recursor/scripting.md, 'Recursor', 'Scripting']
   - [recursor/settings.md, 'Recursor', 'List of Settings']