Show
Ignore:
Timestamp:
04/19/06 13:58:29 (7 years ago)
Author:
ahu
Message:

documentation, plus newline termination of 'pong' :-)

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/pdns/pdns/docs/pdns.sgml

    r698 r739  
    58465846  <chapter id="built-in-recursor"><title>PowerDNS resolver/recursing nameserver</title> 
    58475847    <para> 
    5848       As of 2.9.4, a small recursor comes with PowerDNS. The algorithm is influenced by the works of Dan J. Bernstein although 
    5849       all mistakes are ours. Here are the current faults, so nobody can accuse us of false advertising: 
    5850       <itemizedlist> 
    5851         <listitem><para> 
    5852             Only compiles on Linux, FreeBSD 5.x, Windows and possibly Solaris. FreeBSD 4.x decided not to support the  
    5853             POSIX get/set/swapcontext functions. Bug your favorite FreeBSD kernel or libc maintainer for a fix, 
    5854             or ask him to port MTasker (see below) to your operating system. It may work on recent 4.x systems,  
    5855             let us know! 
    5856           </para></listitem> 
    5857         <listitem><para> 
    5858             May have big problems with truncated packets (solved in 2.9.18) 
    5859           </para></listitem> 
    5860       </itemizedlist> 
     5848      The PowerDNS recursor is part of the source tarball of the main PowerDNS distribution, but it is released separately. Starting from 
     5849      the version 3.0 pre-releases, there are zero known bugs or issues with the recursor. It is known to power the resolving needs of over 2 million 
     5850      internet connections. 
    58615851    </para> 
    58625852    <para> 
    5863       To compile, add <command>--enable-recursor</command> to configure and the file <filename>pdns_recursor</filename> will be  
    5864       compiled. To run on a different port, use <command>./syncres --local-port=53</command>. 
    5865       To bind to another address, use the <command>local-address</command> setting. 
     5853      The documentation below is only for the 3.0 series, users of older versions are urged to upgrade! 
    58665854    </para> 
    5867  
    58685855    <para> 
    5869       Good points: 
     5856      Notable features: 
    58705857      <itemizedlist> 
    58715858        <listitem><para> 
    … …  
    58735860          </para></listitem> 
    58745861        <listitem><para> 
    5875             Can handle thousands of concurrent questions 
     5862            Can handle thousands of concurrent questions. A dual Xeon 3GHz has been measured functioning very well at 9000 real life replayed 
     5863            packets per second, with 40% cpu idle. More testing equipment is needed to max out the recursor. 
    58765864          </para></listitem> 
    5877           <listitem><para> 
    5878           Appears to be very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers. 
     5865        <listitem><para> 
     5866            Powered by a highly modern DNS packet parser that should be resistant against many forms of buffer overflows. 
     5867          </para></listitem> 
     5868        <listitem><para> 
     5869            Best spoofing protection that we know about, involving both source port randomisation and spoofing detection. 
     5870          </para></listitem> 
     5871        <listitem><para> 
     5872            Uses 'connected' UDP sockets which allow the recursor to react quickly to unreachable hosts or hosts for which  
     5873            the server is running, but the nameserver is down. This makes the recursor faster to respond in case of misconfigured domains, 
     5874            which are sadly very frequent. 
     5875          </para></listitem> 
     5876        <listitem><para> 
     5877            Special support for FreeBSD, Linux and Solaris stateful multiplexing (kqueue, epoll, completion ports). 
     5878          </para></listitem> 
     5879        <listitem><para> 
     5880            Very fast, and contains innovative query-throttling code to save time talking to obsolete or broken nameservers. 
    58795881          </para></listitem> 
    58805882        <listitem><para> 
    … …  
    58855887          </para></listitem> 
    58865888        <listitem><para> 
    5887             Is very verbose in showing how recursion actually works. 
     5889            Is very verbose in showing how recursion actually works, when enabled to do so with --verbose. 
    58885890          </para></listitem> 
    58895891        <listitem><para> 
    … …  
    58925894      </itemizedlist> 
    58935895    </para> 
     5896    <para> 
     5897      The PowerDNS recursor is controlled and queried using the <filename>rec_control</filename> tool.  
    58945898    <sect1><title>pdns_recursor settings</title> 
    58955899      <para> 
    58965900        At startup, the recursing nameserver reads the file <filename>recursor.conf</filename> from the configuration directory, 
    5897         often <filename>/etc/powerdns</filename> or <filename>/usr/local/etc</filename>. 
     5901        often <filename>/etc/powerdns</filename> or <filename>/usr/local/etc</filename>. Each setting below can appear on the command line, 
     5902        prefixed by '--', or in the configuration file. The command line overrides the configuration file. 
     5903      </para> 
     5904      <para> 
     5905        A switch can be set to on simply by passing it, like '--daemon', and turned off explicitly by '--daemon=off' or '--daemon=no'. 
    58985906      </para> 
    58995907      <para> 
    … …  
    59145922            <listitem> 
    59155923              <para> 
    5916                 Comma separated netmasks that are allowed to use the server. The default allows complete access! 
    5917               </para> 
    5918             </listitem> 
    5919           </varlistentry> 
     5924                Comma separated netmasks (both IPv4 and IPv6) that are allowed to use the server. The default allows access only from RFC 1918  
     5925                private IP addresses, like 10.0.0.0/8. Due to the agressive nature of the internet these days, it is highly recommended 
     5926                to not open up the recursor for the entire internet. Questions from IP addresses not listed here are ignored and do  
     5927                not get an answer. 
     5928              </para> 
     5929            </listitem> 
     5930          </varlistentry> 
     5931          <varlistentry><term>chroot</term> 
     5932            <listitem><para> 
     5933                If set, chroot to this directory for more security. See <xref linkend="security">. 
     5934              </para></listitem></varlistentry> 
    59205935          <varlistentry> 
    59215936            <term>client-tcp-timeout</term> 
    59225937            <listitem> 
    59235938              <para> 
    5924               Time to wait for data from TCP clients. Defaults to 2 seconds. Available since 2.9.18.  
     5939              Time to wait for data from TCP clients. Defaults to 2 seconds.  
    59255940              </para> 
    59265941            </listitem> 
    … …  
    59515966          </varlistentry> 
    59525967          <varlistentry> 
     5968            <term>fork</term> 
     5969            <listitem> 
     5970              <para> 
     5971                If running on an SMP system with enough memory, this feature forks PowerDNS so it benefits from two processors. Experimental. Renames 
     5972                controlsockets, so care is needed to connect to the right one using <command>rec_control</command>, using <command>--socket-pid</command>. 
     5973              </para> 
     5974            </listitem> 
     5975          </varlistentry> 
     5976 
     5977 
     5978          <varlistentry> 
    59535979            <term>hints-file</term> 
    59545980            <listitem> 
    … …  
    59635989            <listitem> 
    59645990              <para> 
    5965                 Local IP addresses to bind to, comma separated. Defaults to all addresses. 
     5991                Local IPv4 or IPv6 addresses to bind to, comma separated. Defaults to only loopback. 
    59665992              </para> 
    59675993            </listitem> 
    … …  
    59766002            </listitem> 
    59776003          </varlistentry> 
     6004 
     6005          <varlistentry> 
     6006            <term>log-common-errors</term> 
     6007            <listitem> 
     6008              <para> 
     6009                Some DNS errors occur rather frequently and are no cause for alarm. Logging these is on by default. 
     6010              </para> 
     6011            </listitem> 
     6012          </varlistentry> 
    59786013          <varlistentry> 
    59796014            <term>max-cache-entries</term> 
    … …  
    59856020          </varlistentry> 
    59866021          <varlistentry> 
     6022            <term>max-negative-ttl</term> 
     6023            <listitem> 
     6024              <para> 
     6025                A query for which there is authoritatively no answer is cached to quickly deny a record's existence later on, without 
     6026                putting a heavy load on the remote server. In practice, caches can become saturated with hundreds of thousands of hosts 
     6027                which are tried only once. This setting, which defaults to 3600 seconds, puts a maximum on the amount of time negative 
     6028                entries are cached. 
     6029              </para> 
     6030            </listitem> 
     6031          </varlistentry> 
     6032          <varlistentry> 
    59876033            <term>max-tcp-clients</term> 
    59886034            <listitem> 
    … …  
    60086054            </listitem> 
    60096055          </varlistentry> 
    6010           <varlistentry> 
    6011             <term>query-local-port</term> 
    6012             <listitem> 
    6013               <para> 
    6014                 Send out local queries from this port exclusively. Useful for strict firewalls. Random, and possibly changing, if unset. 
    6015               </para> 
    6016             </listitem> 
    6017           </varlistentry> 
     6056 
    60186057          <varlistentry> 
    60196058            <term>quiet</term> 
    60206059            <listitem> 
    60216060              <para> 
    6022                 Don't log queries. 
     6061                Don't log queries. On by default. 
     6062              </para> 
     6063            </listitem> 
     6064          </varlistentry> 
     6065          <varlistentry> 
     6066            <term>remotes-ringbuffer-entries</term> 
     6067            <listitem> 
     6068              <para> 
     6069                Number of entries in the remotes ringbuffer, which keeps statistics on who is querying your server. Can be read out using 
     6070                <command>rec_control top-remotes</command>. Defaults to 0. 
     6071              </para> 
     6072            </listitem> 
     6073          </varlistentry> 
     6074          <varlistentry> 
     6075            <term>server-id</term> 
     6076            <listitem> 
     6077              <para> 
     6078                The PowerDNS recursor by replies to a query for 'id.server' with its hostname, useful for in clusters. Use this setting to override 
     6079                the answer it gives. 
     6080              </para> 
     6081            </listitem> 
     6082          </varlistentry> 
     6083          <varlistentry> 
     6084            <term>set-gid</term> 
     6085            <term>set-uid</term> 
     6086            <listitem> 
     6087              <para> 
     6088                PowerDNS can change its user and group id after binding to its socket. Can be used for better security. 
    60236089              </para> 
    60246090            </listitem> 
    … …  
    60336099          </varlistentry> 
    60346100          <varlistentry> 
     6101            <term>spoof-nearmiss-max</term> 
     6102            <listitem> 
     6103              <para> 
     6104                If set to non-zero, PowerDNS will assume it is being spoofed after seeing this many answers with the wrong id. Defaults to 20. 
     6105              </para> 
     6106            </listitem> 
     6107          </varlistentry> 
     6108          <varlistentry> 
    60356109            <term>trace</term> 
    60366110            <listitem> 
    … …  
    60406114            </listitem> 
    60416115          </varlistentry> 
     6116          <varlistentry> 
     6117            <term>version-string</term> 
     6118            <listitem> 
     6119              <para> 
     6120                By default, PowerDNS replies to the 'version.bind' query with its version number. Security concious users may wish to override 
     6121                the reply PowerDNS issues. 
     6122              </para> 
     6123            </listitem> 
     6124          </varlistentry> 
    60426125        </variablelist> 
    60436126      <para> 
     6127    <sect2 id="rec-control"><title>Controlling and querying the recursor</title> 
     6128        <para> 
     6129          To control and query the PowerDNS recursor, the tool <filename>rec_control</filename> is provided. This program 
     6130          talks to the recursor over the 'controlsocket', often stored in <filename>/var/run</filename>. 
     6131        </para> 
     6132        <para> 
     6133          As a sample command, try: 
     6134          <screen> 
     6135            # rec_control ping 
     6136            pong 
     6137          </screen> 
     6138        </para> 
     6139        <para> 
     6140          When not running as root, <command>--socket-dir=/tmp</command> might be appropriate. 
     6141        </para> 
     6142        <para> 
     6143          All rec_control commands are documented below: 
     6144          <variablelist> 
     6145            <varlistentry> 
     6146              <term>dump-cache filename</term> 
     6147              <listitem> 
     6148                <para> 
     6149                  Dumps the entire cache to the filename mentioned. This file should not exist already, PowerDNS 
     6150                  will refuse to overwrite it. While dumping, the recursor will not answer questions. 
     6151                </para> 
     6152              </listitem> 
     6153            </varlistentry>        
     6154            <varlistentry> 
     6155              <term>get statistic</term> 
     6156              <listitem> 
     6157                <para> 
     6158                  Retrieve a statistic. For items that can be queried, see below. 
     6159                </para> 
     6160              </listitem> 
     6161            </varlistentry>        
     6162            <varlistentry> 
     6163              <term>ping</term> 
     6164              <listitem> 
     6165                <para> 
     6166                  Check if server is alive. 
     6167                </para> 
     6168              </listitem> 
     6169            </varlistentry>        
     6170            <varlistentry> 
     6171              <term>quit</term> 
     6172              <listitem> 
     6173                <para> 
     6174                  Request shutdown of the recursor. 
     6175                </para> 
     6176              </listitem> 
     6177            </varlistentry>        
     6178            <varlistentry> 
     6179              <term>top-remotes</term> 
     6180              <listitem> 
     6181                <para> 
     6182                  Shows the top-20 most active remote hosts. Statistics are over the last 'remotes-ringbuffer-entries' queries, which 
     6183                  defaults to 0. 
     6184                </para> 
     6185              </listitem> 
     6186            </varlistentry>        
     6187            <varlistentry> 
     6188              <term>wipe-cache domain0. [domain1. domain2.]</term> 
     6189              <listitem> 
     6190                <para> 
     6191                  Wipe entries from the cache. This is useful if, for example, an important server has a new IP address, but the TTL has not 
     6192                  yet expired. Multiple domain names can be passed. Note that you must terminate a domain with a .! So to wipe powerdns.org, 
     6193                  issue 'rec_control wipe-cache powerdns.org.'. 
     6194                </para> 
     6195                <para> 
     6196                  <warning> 
     6197                    <para> 
     6198                      Ubunty Breezy ships a version of Boost that has problems with this command! Either refrain from 
     6199                      using wipe-cache or download a more recent Boost into the PowerDNS source directory, as explained in the 
     6200                      <filename>README</filename> 
     6201                    </para> 
     6202                  </warning> 
     6203                </para> 
     6204              </listitem> 
     6205            </varlistentry>        
     6206          </variablelist> 
     6207        </para> 
     6208        <para> 
     6209          The command 'get' can query a large number of statistics, which are detailed in <xref linkend="recursor-stats">. 
     6210 
     6211        </para> 
     6212        <para> 
     6213          More details on what 'throttled' queries and the like are can be found below in <xref linkend="recursor-details">. 
     6214        </para> 
     6215      </sect2> 
     6216 
    60446217    <sect2 id="verisign"><title>Verisign weirdness</title> 
     6218        <para> 
     6219          <note> 
     6220            <para> 
     6221              Verisign backed off, this feature is no longer needed (for now). 
     6222            </para> 
     6223          </note> 
     6224        </para> 
    60456225        <para> 
    60466226          Verisign, the current operator of the COM and NET zones, decided to add a wildcard record so as to draw all queries for non-existing  
    … …  
    60626242 
    60636243    </sect1> 
    6064     <sect1><title>Details</title> 
     6244    <sect1 id="recursor-details"><title>Details</title> 
    60656245      <para> 
    60666246        PowerDNS implements a very simple but effective nameserver. Care has been taken not to overload remote servers in case 
    … …  
    60936273      </para> 
    60946274    </sect1> 
    6095     <sect1><title>Statistics</title> 
     6275    <sect1 id="recursor-stats"><title>Statistics</title> 
     6276      <para> 
     6277        The <command>rec_control get</command> command can be used to query the following keys, either single keys or multiple keys  
     6278        at once: 
     6279          <screen> 
     6280all-outqueries      counts the number of outgoing UDP queries since starting 
     6281answers0-1          counts the number of queries answered within 1 milisecond 
     6282answers100-1000     counts the number of queries answered within 1 second 
     6283answers10-100       counts the number of queries answered within 100 miliseconds 
     6284answers1-10         counts the number of queries answered within 10 miliseconds 
     6285answers-slow        counts the number of queries answered after 1 second 
     6286cache-entries       shows the number of entries in the cache 
     6287cache-hits          counts the number of cache hits since starting 
     6288cache-misses        counts the number of cache misses since starting 
     6289client-parse-errors counts number of client packets that could not be parsed 
     6290concurrent-queries  shows the number of MThreads currently running 
     6291negcache-entries    shows the number of entries in the Negative answer cache 
     6292noerror-answers     counts the number of times it answered NOERROR since starting 
     6293nsspeeds-entries    shows the number of entries in the NS speeds map 
     6294nxdomain-answers    counts the number of times it answered NXDOMAIN since starting 
     6295outgoing-timeouts   counts the number of timeouts on outgoing UDP queries since starting 
     6296qa-latency          shows the current latency average 
     6297questions           counts all End-user initiated queries with the RD bit set 
     6298resource-limits     counts number of queries that could not be performed because of resource limits 
     6299server-parse-errors counts number of server replied packets that could not be parsed 
     6300servfail-answers    counts the number of times it answered SERVFAIL since starting 
     6301spoof-prevents      number of times PowerDNS considered itself spoofed, and dropped the data 
     6302sys-msec            number of CPU milliseconds spent in 'system' mode 
     6303tcp-client-overflow number of times an IP address was denied TCP access because it already had too many connections 
     6304tcp-outqueries      counts the number of outgoing TCP queries since starting 
     6305tcp-questions       counts all incoming TCP queries (since starting) 
     6306throttled-out       counts the number of throttled outgoing UDP queries since starting 
     6307throttle-entries    shows the number of entries in the throttle map 
     6308unauthorized-tcp    number of TCP questions denied because of allow-from restrictions 
     6309unauthorized-udp    number of UDP questions denied because of allow-from restrictions 
     6310unexpected-packets  number of answers from remote servers that were unexpected (might point to spoofing) 
     6311user-msec            number of CPU milliseconds spent in 'user' mode 
     6312          </screen> 
     6313        In the <filename>rrd/</filename> subdirectory a number of rrdtool scripts is provided to make nice 
     6314        graphs of all these numbers. 
     6315      </para> 
    60966316      <para> 
    60976317        Every half our or so, the recursor outputs a line with statistics. More infrastructure is planned so as to allow