                       ************ ppddnnssdd DDooccuummeennttaattiioonn ************
********** 00.. IInnssttaallllaattiioonn **********
******** 00..11 IInnssttaalllliinngg bbiinnaarryy RRPPMM''ss ********
To install a binary RPM, just do
rpm -i pdnsd-<version>.rpm
This should install pretty much everything automatically. The only thing left
for you to do is adatpt your configuration file (stored in /etc/pdnsd.conf)
according to your needs (see below). In the SuSE RPMs, a start script is also
installed; read the section 0.4, Start at Boot Time about that.
******** 00..22 IInnssttaalllliinngg ssoouurrccee RRPPMM''ss ********
To install a source RPM, just do
rpm --recompile pdnsd-<version>.rpm
This should install pretty much everything automatically. The only thing left
for you to do is adapt your configuration file (stored in /etc/pdnsd.conf)
according to your needs. In the SuSE RPMs, a start script is also installed;
read the section Start at Boot Time about that.
******** 00..33 IInnssttaalllliinngg ffrroomm tthhee ppuurree ssoouurrcceess ((ttaarr aarrcchhiivveess)) ********
****** 00..33..11 DDeeccoommpprreessssiinngg ******
pdsnsd comes in two different packed archives: the standard gzip'ed version
pdnsd-<version>.tar.gz, and the bzip2-packed version (about 10% smaller) pdnsd-
<version>.tar.bz2. If you have bunzip2 installed on your computer, I recommed
you save bandwidth and get the .bz2-version. To decompress it (using a modern
tar) do
tar -xzf pdnsd-<version>.tar.gz
--or--
tar -xIf pdnsd-<version>.tar.bz2

If your tar doesn't do this, use:
gunzip pdnsd-<version>.tar.gz
tar -xf pdnsd-<version>.tar
--or--
bunzip2 pdnsd-<version>.tar.bz2
tar -xf pdnsd-<version>.tar
****** 00..33..22 SSeettuupp ******
Change into the pdnsd source directory and run configure. It takes the
following command line options (if you do not specify an option, defaults will
be used):
                            Specify the prefix directory. The pdnsd files are
                            installed in subdirectories of the prefix, the
--prefix=dir                pdnsd and pdnsd-ctl executables are for example
                            installed in the sbin subdirectory of the prefix.
                            The default for this is /usr/local; you might want
                            to set this to /usr (using --prefix=/usr).
                            Specify target distribution (default=Generic;
--with-distribution=distro  others: RedHat, SuSE, Debian)
                            See below for the effect of these settings.
                            Change compilation target platform (default:
                            autodetect; others: Linux, BSD)
--with-target=platform      autodetect will attempt to detect whether you are
                            using *BSD or Linux and should normally be
                            sufficient. If this does not work, try specifyning
                            you system manually.
                            Default directory for pdnsd cache (default=/var/
--with-cachedir=dir         cache/pdnsd)
                            This setting can be changed via config file
                            settings when pdnsd was built.
                            Default directory for the pdnsd control socket
                            (default=/tmp)
--with-tempedir=dir         This sets where pdnsd creates its control socket,
                            and where pdnsd-ctl tries to find it. There should
                            be rarely need to change this setting.
                            Specifiy database manager to use for cacheing
--with-dbm=dbm              (default=native; others: gdbm)
                            Currently, only native will work.
                            Enable ISDN support
                            This option will work only on Linux and may cause
--enable-isdn               problems with 2.0.x or old 2.2.x kernels. You will
                            need it for a proper if uptest under Linux for ISDN
                            ppp devices.
--disable-ipv4              Disable IPv4 networking support (default=enabled)
                            Enable IPv6 networking support.
--enable-ipv6               If your OS does support IPv6 properly, you should
                            be able to serve also IPv4 queries using this.
                            Normally, this is disabled and you won't need it.
--disable-ipv4-startup      Disable IPv4 on pdnsd startup by default
                            (default=enabled)
                            Enable IPV6 on pdnsd startup by default
                            (default=IPv4). These options are only defaults,
--enable-ipv6-startup       you can specify on the command line or in the
                            config files which IP version will really be used.
                            Normally, you won't need to change these.
--disable-udp-queries       Disable udp as query method. You shouldn't need to
                            change this.
--enable-tcp-queries        Enable tcp as query method. This is normally not
                            needed.
                            Specify the query method (default=udponly, others:
                            tcpudp, tcponly) If you have enabled both udp and
                            tcp queries, this lets you control which query
--with-query-method=qm      method pdnsd will use ny default. tcpudp will try
                            tcp first and back out to udp if tcp is not
                            supported by the server; udponly and tcponly should
                            be clear.
--enable-tcp-server         Enable the TCP serving ability of pdnsd.
                            This is seldom needed in normal usage.
                            Disable the UDP source address discovery.
--disable-src-addr-disc     You need this only if you have trouble with
                            messages saying "could not discover udp source
                            address".
--disable-poll              Disable poll(2) and use select(2) (default=enabled)
                            You will normally not need this.
                            Enable new DNS RR types. Recommended if IPV6 is
                            enabled. The new types are RP, AFSDB, X25, ISDN,
--enable-new-rrs            RT, NSAP, PX, GPOS, AAAA, LOC, EID, NIMLOC, SRV,
                            ATMA, NAPTR and KX. Most of these are seldomly
                            needed, but AAAA is essential when using IPv6.
                            Enforce strict RFC 2181 compliance.
                            This will cause pdnsd to reject DNS answers with
--enable-strict-rfc2181     incorrect timestamp settings (multiple RRs of the
                            same type and for the same domain with different
                            TTLs). Normally not needed.
                            Specify random device; default: C Library internal
                            RNG
                            pdnsd uses random numbers as query IDs for security
                            reasins (this makes forged DNS answers more
                            difficult). This option controls where pdnsd gets
                            these from. The default is the internal random
--with-random-device=device number generator of the C lobrary, which should
                            suffice. You can specify a device like /dev/urandom
                            here if you like; pdnsd will read random numbers
                            from it 16-bit-wise. /dev/urandom is present under
                            Linux and most BSD derivates. You should not use /
                            dev/random - whis is more secure, but may block and
                            delay pdnsd's answers for a long time.
                            Specify default user for pdnsd (default=nobody).
                            This is the user that will be entered for the
--with-default-id=user      run_as option in the config file (see below) that
                            will be installed during make install. You can
                            change this any time in your config file.
                            Specify debugging level. Debug output will only be
--with-debug=level          generated if you turn on special switches; it might
                            be useful for debugginh your config files, so I
                            recommend using the default (9).
--with-verbosity=level      Specify default message verbosity. The default
                            should be ok.
                            Enable RCS IDs in executables (default=disabled).
--enable-rcsids             For personal use, there is no need to do this. If
                            you build rpm's, it might have advantages.
                            Enable subsequent tcp queries. The DNS protocol
                            standard requires that servers must be capable of
                            answering multiple subsequent queries that are sent
                            over the same tcp connection, and that the server
                            may only close the connection by himself after a
                            certain timeout. This feature is rarely used, but
--enable-tcp-subseq         may make denial-of-service attacks easier, as it
                            allows for an attacker to hold a connection open a
                            long time (although the attacker's IP is most
                            likely revealed then). For full standard
                            compliance, you should use this option. If you do
                            not use --enable-tcp-server, is option is not
                            honored.
                            Specify default tcp query timeout after which the
                            connection is closed if no full query has been
--with-tcp-qtimeout         received. The default is 30s. You can also change
                            this option at run time using th tcp_qtimeout
                            config file option. If you do not use --enable-tcp-
                            server, is option is not honored.
                            Specify the default number of queries that can be
                            executed in parallel. You can also change this
--with-par-queries          option at run time using th par_queries config file
                            option. See the description of that option for an
                            explanation of what it really does.
                            The default for this option is 2.
Normally, you will need only --prefix and --with-distribution. If you specify
your distribution using --with-distribution, this has the following effects:
    * An rc script is copied in the appropriate localtion, which enables pdnsd
      to start at machine boot time (see 0.4)
    * Distribution-specific portions might be included in the generated
      pdnsd.spec file (only important if you want to build rpm archives
      yourself).
If you choose Generic, no rc script is installled, and a generic spec file is
generated.
Further instructions are in the INSTALL document in the pdsd source directory.
./configure --help will give you a list of all supported command line options.
****** 00..33..33 BBuuiillddiinngg && iinnssttaalllliinngg ******
Type make in the source directory. Should work by now.
To install, type make install or do the installation by hand (see 0.3.4).
make install will do the following ($prefix is the prefix directory; see
above):
   1. copies pdnsd to $(prefix)/sbin/
   2. copies pdnsd-ctl to $(prefix)/sbin/
   3. copies docs/pdnsd.conf (a sample configuration) to /etc/ (and backs up /
      etc/pdnsd.conf to /etc/pdnsd.conf.old. If you hhaavvee an /etc/pdnsd.conf.old
      you do not want to be overwritten, save it to another place/name before
      doing make install!
   4. creates your cache directory if it is not there. After installation, you
      should check the file permissions and edit /etc/pdnsd.conf to fit your
      needs (see below). If you use the run_as option, please make sure that
      your cache directory is owned by the user you specified with this option!
You must be root for this installation!
SSeeccuurriittyy nnootteess:: nneevveerr make the pdnsd cache directory writeable for untrusted
users, or you will get several security holes: the users might modify the cache
contents, or plant dangerous links.
If you use a pidfile, you should be aware that you introduce security problems
if you place the pidfile in a directory in a NFS filesystem that is writeable
for untrusted users. Generally, the pidfile directory (typically /var/run)
should not be writeable for untrusted users.
****** 00..33..44 MMaannuuaall iinnssttaallllaattiioonn ******
For a manual installation, you need to do the following steps:
   1. Copy pdnsd and pdnsd-ctl from your build directory to an appropriate
      location (e.g. /usr/sbin).
   2. Copy docs/pdnsd.conf into the directory you want it to reside (/etc by
      default, and change it according to your needs (see below).
   3. Create your caching directory; default is /var/cache/pdnsd (you may
      change this in your pdnsd.conf); Permisions should be at max rwxr-xr-x
      (if you want to protect your cache and status pipe, make it rwx------).
      If you want your status pipe to have different permissions than r-------
      -, do:
      mkfifo <your cache directory>/status -m <your desired permissions>
Thats it!
******** 00..44 SSttaarrtt aatt bboooott ttiimmee ********
In the rc folder of the pdnsd distribution are start scripts for pdnsd designed
for different Linux distros. There are scripts for SuSE and Redhat Linux now.
The start scripts are automatically installed during RPM install, and also
during make install if you specified your distro.
****** 00..44..11 SSuuSSEE LLiinnuuxx ssttaarrttuupp ******
rc/SuSE/pdnsd is a start script for SuSE Linux. It was tested for 6.? but
should run on some versions below. You can do make install as root in the rc/
SuSE directory to install it, or you can install manually:
mmaannuuaall iinnssttaallllaattiioonn
For manual installation, copy rc/SuSE/pdnsd into /sbin/init.d/, go to /sbin/
init.d/rc2.d/ and create there the following two symlinks:
S11pdnsd to ../pdnsd (do ln -s ../pdnsd S11pdnsd in that dir)
K34pdnsd to ../pdnsd (do ln -s ../pdnsd K34pdnsd in that dir)
The numbers dictate the order different services are started and might need to
be modified. Then edit your /etc/rc.config file and add the line
START_PDNSD=yes to start pdnsd at boot time.
If you used the make install command, START_PDNSD=yes has been appended to your
/etc/rc.config file, causing pdnsd to be started at boot time. If you don't
want that, change the yes into no.
This start script was created from /sbin/init.d/skeleton by me, so the most is
copyrighted by SuSE. They put it under the GPL, however, so the license stated
in _C_O_P_Y_I_N_G also applies to this script. There is NO WARRANTY OF ANY KIND on
these scripts. This is no official SuSE script, and SuSE naturally does NO
support for it.
****** 00..44..22 RReedd HHaatt LLiinnuuxx ssttaarrttuupp ******
rc/Redhat/pdnsd is a start script for Red Hat Linux. It was contibuted by
Torben Janssen.
This was tested for 6.1 but should run on 5.0+. You can do make install as root
in the rc/Redhat directory to install it, or you can install manually:
mmaannuuaall iinnssttaallllaattiioonn
For manual installation, copy rc/Redhat/pdnsd into /etc/rc.d/init.d/
Then go to /etc/rc.d/rc3.d and create there the following symlink:
S78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd S78pdnsd in that dir)
Then go to /etc/rc.d/rc0.d and create there the following symlink:
K78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd K78pdnsd in that dir)
Then go to /etc/rc.d/rc6.d and create there the following symlink:
K78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd K78pdnsd in that dir)
This script is also covered by license stated in _C_O_P_Y_I_N_G. Again, there is NO
WARRANTY OF ANY KIND on these scripts. This is no offical Redhat script, and
Redhat naturally does NO support for it
******** 00..55 NNootteess ffoorr FFrreeeeBBSSDD--uusseerrss ********
The special handling of ISDN ppp devices is only supported on Linux. It is not
needed in FreeBSD, the normal device handling also works fine with isdn4bsd
devices.
When compiled for FreeBSD, pdnsd as a small RFC compatability issue: RFC2181
demands answers on dns querys to be sent with the same source address the query
packet went to. This is currently not implemented for FreeBSD, and I am
investigating ways to port the Linux code.


********** 11 IInnvvooccaattiioonn **********
When invoking pdnsd, you can specify various options at the command line.
Command line options always override config file options. The various ----nnooXX
options are present to override config file options.
pdnsd ----hheellpp (or --hh) gives you an overview of the pdnsd command line options.
pdnsd ----vveerrssiioonn (or --VV for short) prints licence and version information.
To start pdnsd as background daemon, specifiy ----ddaaeemmoonn (or --dd for short) on the
command line. Diagnostic and error messages after the actual daemon start will
be printed to the syslog instead of the console. ----nnooddaaeemmoonn will disable this.
When starting pdnsd as a daemon, the --pp option may be helpful: It writes the
pid of the server process to the file of the name given as argument to this
option.
Example: pdnsd -d -p /var/run/pdnsd.pid
If you want to specify a configuration file other that /etc/pdnsd.conf, specify
--cc or ----ccoonnffiigg--ffiillee on the command line, followed by a filename.
If pdnsd was compiled with debugging options enabled, you may specify --gg or ----
ddeebbuugg on the command line. This will cause extra diagnostic messages to be
printed. When pdnsd runs in deamon mode, the messages will be written to the
pdnsd.debug file in your cache directory. ----nnooddeebbuugg disables debugging.
pdnsd --vvnn sets the verbosity level of pdnsd. n may be a digit from 0 to 3,
where 0 means normal operation, while 3 will most verbose. Example is -v2
The option --ss or ----ssttaattuuss enables the status pipe. This is a named pipe in the
server directory called status. You can read the server status by doing
cat <your cache directory>/status. ----nnoossttaattuuss disables the status pipe.
The option --tt or ----nnoottccpp disables the seldom needed TCP server thread, which
may save you some resources. ----ttccpp will enable it.
Using the --mm option, you can select the method pdnsd uses to query other name
servers. Following methods are supported:
--mmuuoo: pdnsd will use UDP only. This is the fastest method, and should be
supported by all name servers on the internt.
--mmttoo: pdnsd will use TCP only. TCP queries usually take longer time than UDP
queries, but are more secure against certain attacks, where an attacker tries
to guess your query id and to send forged answers. TCP queries are not
supported by some name servers.
--mmttuu: pdnsd will try to use TCP, and will fall back to UDP if its connection is
refused.
********** 22 TThhee ccoonnffiigguurraattiioonn ffiillee **********
This section describes the layout of the configuration file and the available
configuration options. The default location of the file is /etc/pdnsd.conf.
This may be changed with the -c command line option. An example pdnsd.conf
comes with the pdnsd distribution in the docs directory and will be installed
to /etc/ by make install.
******** 22..11 LLaayyoouutt ********
The configuration file is divided into sections. Each section is prefixed with
the section name and opening curlies ({) and closed with closing curlies (}).
In each section, configuration options can be given in the form
option_name=option_value;
Option value may be a string literal (enclosed in "), a number or a constant.
Constants are noted in the section description in <> signs, but are written in
the file without these signs. Some options take more than one value; in this
case, the values are separated with commas.
If you may supply one of a set of possible values to an option, this is noted
in the documentation as
(option1|option2|option3|...)
Comments may be onclosed in /* and */, nested comments are possible. If the #
sign or two slashes (//) appear in the configuration file, everything from
these signs to the end of the current line is regarded as a comment and
ignored.
There are examples for nearly all options in the sample config file.
******** 22..11..11 gglloobbaall SSeeccttiioonn ********
The global section specifies parameters that affect the overall behaviour of
the server. If you specify multiple global sections, the settings of those
later in the file will overwrite the earlier given values.
These are the possible options:

ppeerrmm__ccaacchhee==((nnuummbbeerr||<<ooffff>>));;
Switch the disk cache off or supply a maximum cache size in kB. If the disk
cache is switched off, 4 bytes will still be written to disk. The memory cache
is always 10kB larger than the file cache. This value is 2048 (2 MB) by
default.
ccaacchhee__ddiirr==ssttrriinngg;;
Set the directory you want to keep the cache in. The default is "/var/cache/
pdnsd".
sseerrvveerr__ppoorrtt==nnuummbbeerr;;
Set the server port. This is especially useful when you want to start the
server and are not root. Note that you may also not specify uptest=ping in the
server section as non-root.
The default port is 53, the RFC-standard one. Note that you should only use
non-standard ports when you only need clients on your machine to communicate
with the server; others will probably fail if the try to contact the server on
the basis of an NS record, since the A record that supplies the address for
(among others) name servers does not have a port number specification.
sseerrvveerr__iipp==ssttrriinngg;;
Set the ip address pdnsd listens on for requests. This can be useful when the
host has several interfaces and you want pdnsd not to listen on all interfaces.
Addtionally, it is possibly to bind pdnsd to listen on 127.0.0.2 to allow pdnsd
to be a forwarder for BIND. pdnsd will listen on all of your local interfaces
by default. The ip is treated as string and therefore needs to have quotation
marks around it.
lliinnkkddoowwnn__kklluuggee==((<<oonn>>||<<ooffff>>));;
This option enables a kluge that some people might need: when all servers are
marked down, with this option set the cache is not even used when a query is
received, and a DNS error is returned in any case. The only exception from this
is that local records (as specified in rr and source sections are still served
normally. In general, you probably want to get cached entries even when the
network is down, so this defaults to off.
mmaaxx__ttttll==nnuummbbeerr;;
This options sets the maximum time a record is hold in cache in seconds. All
dns resource records have a time to live field that says for what period of
time the record may be cached before it needs to be requeried. If this is more
than the value given with max_ttl, this time to live value is set to max_ttl.
This is done to prevent records from being cached an inappropriate long period
of time, because that is almost never a good thing to do. Default is 604800s
(one week).
rruunn__aass==ssttrriinngg;;
This option allows you to let pdnsd change its user and group id after
operations that needed privileges have been done. This helps minimize security
risks and is therefore recommended. The supplied string gives a user name whose
user id and primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if
specified) and starting the server status thread, the main thread changes its
gid and uid, as do all newly created threads thereafter. By taking another uid
and gid, those threads run with the privileges of the specified user. Under
Linux and FreeBSD, the server status thread runs with the original privileges
only when the strict_setuid option is set to off (see below, on by default),
because these may be needed for exec uptests. The manager thread also retains
its original privileges in this case. You should take care that the user you
specify has write permissions on your cache file and status pipe (if you need a
status pipe). You should look out for error messages like "permission denied"
and "operation not permitted" to discover permission problems.
ssttrriicctt__sseettuuiidd==((<<oonn>>||<<ooffff>>));;
When used together with the run_as option, this option lets you specify that
all threads of the program will run with the privileges of the run_as user.
This provides higher security than the normal run_as option, but is not always
possible. See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
ppaarraannooiidd==((<<oonn>>||<<ooffff>>));;
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers
to query other servers themselves if possible, and to give back answers for
domains that may not be in its authority), and accepts additional records with
information for servers that are not in the authority of the queried server.
This opens the possibility of so-called cache poisoning: a malicious attacker
might set up a dns server that, when queried, returns forged additional
records. This way, he might replace trusted servers with his own ones by making
your dns server return bad IP addresses. This option protects you from cache
poisoning by rejecting additional records that do not describe domains in the
queried servers authority space and not doing recursive queries any more. An
exception to this rule are the servers you specify in your config file, which
are trusted.
The penalty is a possible performance decrease, in particular, more queries
might be necessary for the same operation.
You should also notice that there may be other similar security problems, which
are essentially problems of the DNS, i.e. any "traditional" server has them
(the DNS security extensions solve these problems, but are not widely
supported). One of this vulnerabilities is that an attacker may bombard you
with forged answers in hopes that one may match a query you have done. If you
have done such a query, one in 65536 forged packets will be succesful (i.e. an
average packet count of 32768 is needed for that attack). pdnsd can use TCP for
queries, which has a slightly higher overhead, but is much less vulnerable to
such attacks on sane operating systems. Also, pdnsd chooses random query ids,
so that an attacker cannot take a shortcut. If the attacker is able to listen
to your network traffic, this attack is relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional
name server (pdnsd is perhaps a little more secured against this type of
attacks if you make it use TCP).
The paranoid option is off by default.
sscchheemmee__ffiillee==ssttrriinngg;;
In addition to normal uptests, you may specify that some servers shall only be
queried when a certain pcmcia-cs scheme is active (only under linux). For that,
pdnsd needs to know where the file resides that holds the pcmcia scheme
information. Normally, this is either /var/lib/pcmcia/scheme or /var/state/
pcmcia/scheme.
ssttaattuuss__ccttll==((<<oonn>>||<<ooffff>>));;
This has the same effect as the -s command line option: the status control is
enabled when on is specified.
ddaaeemmoonn==((<<oonn>>||<<ooffff>>));;
This has the same effect as the -d command line option: the daemon mode enabled
when on is specified.
ttccpp__sseerrvveerr==((<<oonn>>||<<ooffff>>));;
This has the same effect as the -t command line option: the tcp serving ability
is enabled when on is specified.
ppiidd__ffiillee==ssttrriinngg;;
This has the same effect as the -p command line option: you can specify a file
that pdnsd will write its pid into when it starts in daemon mode.
vveerrbboossiittyy==nnuummbbeerr;;
This has the same effect as the -v command line option: you can set the
verbosity of pdnsd's messages with it. The argument is a number between 0 (few
messages) to 3 (most messages).
qquueerryy__mmeetthhoodd==((<<ttccpp__oonnllyy>>||<<uuddpp__oonnllyy>>||<<ttccpp__uuddpp>>));;
This has the same effect as the -m command line option. Read the documentation
for the command line option on this. tcp_only corresponds to the to, udp_only
to the uo and tcp_udp to the tu argument of the command line option.
rruunn__iippvv44==((<<oonn>>||<<ooffff>>));;
This has the same effect as the -4 command line option: if on is specified,
IPv4 support is enabled, and IPv6 support is disabled (if available). ff off is
specified, IPv4 will be disabled and IPv6 will be enabled. You can only use
this option if you have compiled pdnsd with IPv4 as well as with IPv6 support.
ddeebbuugg==((<<oonn>>||<<ooffff>>));;
This has the same effect as the -g command line option: the debugging messages
are enabled when on is specified.
ccttll__ppeerrmmss==nnuummbbeerr;;
This option allows you to set the file permissions that the pdnsd status
control socket will have. These are the same as file permissions. The owner of
the file will be the run_as user, or, if none is specified, the user who
started pdnsd. If you want to specify the permissions in octal (as usual),
don't forget the leading zero (0600 instead of 600!). To use the status
control, write access is needed. The default is 0600 (only the owner may read
or write).
pprroocc__lliimmiitt==nnuummbbeerr;;
With this option, you can set a limit on the pdnsd threads that will be active
simultaneously. If this number is exceeded, queries are queued and may be
delayed some time. See also the procq_limit option.
The default for this option are 20 query threads will be active (plus 3 to 6
threads that will always be present depending on your configuration).
pprrooccqq__lliimmiitt==nnuummbbeerr;;
When the query thread limit is exceeded, connection attempts to pdnsd will be
queued. With this option, you can set the maximum queue length. If this length
is also exceeded, the incoming queries will be dropped. That means that tcp
connections will be closed and udp queries will just be dropped, which will
probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option.
The default for this option is 30.
ttccpp__qqttiimmeeoouutt==nnuummbbeerr;;
This option sets a timeout for tcp queries. If no full query has been received
on a tcp connection after that time has passed, the connection will be closed.
The default is set using the --with-tcp-qtimeout option to configure.
ppaarr__qquueerriieess==nnuummbbeerr;;
This option sets the maximum number of queries that will be executed in
parallel, i.e. how many servers are simultaneously queried. This may speed up
the query process if there are very slow servers to be quered (the first answer
we get will be taken), but it will also increase network and server load. 1 or
2 are good values for this option. The default is set using the --with-par-
queries option to configure.

******** 22..11..22 sseerrvveerr SSeeccttiioonn ********
Each server section specifies a name server that pdnsd should try to get
resource records or authoritative name server information from. The servers a
queried in the order of their appearance (or parallel to a limited extend). If
one fails, the next one is taken and so on.
You probably want to specify the dns server in your LAN, the caching dns server
of your internet provider or even one of the root servers using server records.
The supported options in this section are:

iipp==ssttrriinngg;;
Give the ip (the ip, _not_ the hostname) of the server. Must be specified.
ppoorrtt==nnuummbbeerr;;
Give the port the remote name server listens on. Default is 53 (the official
dns port)
uupptteesstt==((<<ppiinngg>>||<<nnoonnee>>||<<iiff>>));;
Determine the method to check whether the server is available. Currently
defined methods are:
    * ppiinngg: Send an ICMP_ECHO request to the server. If it doesn't respond in
      timeout, it is regarded to be unavailable until the next probe.
    * nnoonnee: The server is p.d. up
    * iiff: Check whether the interface (specified in the interface= option) is
      existent, up and running. This currently works for all "ordinary" network
      interfaces, interfaces that disappear when down (eg ppp?), and
      additionally for Linux isdn interfaces (as of kernel 2.2). Note that you
      need a /dev/isdninfo device file (major#45, minor#255), or the isdn
      uptest will always fail.
    * ddeevv and ddiiaalldd: Perform an if uptest, and, if that was succesful,
      additionally check whether a program is running that has locked a given
      (modem-) device. The needed parameters are an interface (specified as for
      the if uptest, e.g. "ppp0") and a device relative to /dev (e.g. "modem"
      for /dev/modem specified using the device= option. pdnsd will then look
      for a pid file for the given interface in /var/lock (e.g. /var/run/
      ppp0.pid) and for a lockfile for the given device (e.g. /var/lock/
      LCK..modem), and then test whether the locking process is the process
      that created the pid file and this process is still alive. If this is the
      case, the normal if uptest is executed for the given interface.
      The dev option is for pppd dial-on-demand, diald is the same for diald
      users.
    * eexxeecc: Executes a given command in the /bin/sh shell (as /bin/sh -
      c <command>) and evaluates the result (the retur code of the last
      command) in the shell's way of handling return codes, i.e. 0 indicates
      success, all other indicate failure. The shell's process name will be
      uptest_sh. The command is given with the uptest_cmd option (see below).
      For secuity issues, also see that entry.
The default value is nnoonnee.

NNOOTTEE: If you use demand dialling, use none, if or exec, since ping will send
packets in the specified interval and the interface will thus frequently dial!
ppiinngg__ttiimmeeoouutt==nnuummbbeerr;;
Sets the timeout for the ping test in tenth of seconds. The default is 600.
ppiinngg__iipp==ssttrriinngg;;
The ip for the ping test. The default is the ip of the name server.
uupptteesstt__ccmmdd==ssttrriinngg,,ssttrriinngg;;
or
uupptteesstt__ccmmdd==ssttrriinngg;;
Sets the command for the uptest=exec function to the first string. If the
second string is given, it specifies a user with whose user id and primary
group id the command is executed.
This is especially useful if you are executing the server as root, but do not
want the uptest to be performed with root privileges. In fact, you should never
execute the uptest as root if you can help it.
If the server is running setuid or setgid, the privileges gained such are
dropped even before changin identity to the specified user to prevent setuid/
gid security holes (otherwise, any user might execute commands as root if you
setuid the executable).
The command is executed using /bin/sh, so you should be able to use shell
builtin commands.
iinntteerrvvaall==nnuummbbeerr;;
Sets the interval for the server-up-test in seconds. The default is 900;
however, a test is forced when a query times out. The interval timeout is reset
then.
If you specify onquery instead of a timeout, the interface will be tested
before every query. This is to prevent automatically dialling interfaces
(diald/pppd or ippp) to dial on dns queries. It is intended to be used in
connection with a interface testing uptest ;-)
Note that using uptest=exec, you might run into performance problems on slow
machines when you use that option. DON'T use this option with ping, as it may
cause delays if the server does not answer (btw, it doesn't make sense anyway).
Note also that using that option is no guarantee that the interface will not be
used. When another (reachable) dns server tells pdnsd to query a third dns
server for data, pdnsd will do that and has no means of checking whether this
will dial up the interface or not. This however should be a rare configuration.
iinntteerrffaaccee==ssttrriinngg;;
The network interface (or network device, eg "eth0") for the uptest=if option.
Must be specified if uptest=if is given.
ddeevviiccee==ssttrriinngg;;
The (modem-) device that is used for the dev uptest. If you use this for a
dial-on-demand ppp uptest (together with uptest=dev), you need to enter the
device you are using for your pppd here, e.g. modem for /dev/modem.
Must be specified if uptest=dev is given.
ttiimmeeoouutt==nnuummbbeerr;;
Set the timeout for the dns query in seconds. The default is 120. You probably
want to set this lower.
ppuurrggee__ccaacchhee==((<<oonn>>||<<ooffff>>));;
In every fetched dns record, there is a cache timeout given, which specifies
how long the fetched data may be cached until it needs to be reloaded. If
purge_cache is set to no, the cached records are not purged (unless the cache
size would be exceeded, in this case the oldest records are purged). Instead,
they are still served if they cannot succesfully be updated (eg. because all
servers are down).
ccaacchhiinngg==((<<oonn>>||<<ooffff>>));;
Specifies if caching shall be performed for this server at all. Default is on.
lleeaann__qquueerryy==((<<oonn>>||<<ooffff>>));;
Specifies whether to use the "lean" query mode. In this mode, only the
information actually queried from pdnsd is resolved and cached. This has the
advantage that usually less cache space is used and the query is usually
faster. In 90% of the cases, only address (A) records are needed anyway. If
switched off, pdnsd will always cache all data about a host it can find (well,
at least it is a good approximation for what it really does ;-)
Some buggy name servers may not deliver CNAME records when not asked for all
records. I do not know if such servers are around, but if you have trouble
resolving certain hostnames, try turning this option off.
A last note: If you use multiple pdnsd's that access each other, turning this
option on is probably a big win.
This on by default.
sscchheemmee==ssttrriinngg;;
You can specify a pcmcia-cs scheme that is used in addition to the uptests. If
you specify a scheme here, the server this section is for will only be queries
if the given scheme is active. Shell wildcards (* and ?) are allowed in the
string under their special meanings. You need to use the scheme_file option on
the global section to make this option work.
pprreesseett==((<<oonn>>||<<ooffff>>));;
This allows you to specify the initial state of a server before any uptest is
performed. on specifies that the server is regarded available. The default is
on. This is especially useful when you set uptest=none; and want to control a
server only via pdnsd-ctl.
pprrooxxyy__oonnllyy==((<<oonn>>||<<ooffff>>));;
When this option is set to on, answers given by the servers are always
accepted, and no other servers (as, for example, specified in the NS records of
the query domain) are queried. If you do not turn this option on, pdnsd will do
such queries in some cases (in particular when processing ANY queries).
This option is useful when you do not want pdnsd to make connections to outside
servers for some reasons (e.g. when a firewall is blocking such queries).
I recommend that you turn on lean_query when using this option.
Default is off.
ppoolliiccyy==((<<iinncclluuddeedd>>||<<eexxcclluuddeedd>>));;
pdnsd supports inclusion/exclusion lists for server sections: with include= and
exclude= (see below) you can specifiy domain names for that this server will be
used or will not be used. The first match counts (i.e., the first include or
exclude rule in a server section that matches a domain name is applied, and the
search for other rules is terminated). If no rule matched a given domain name,
the policy= option determines whether this server is used for the lookup for
that domain name; when included is given, the server will be asked, otherwise
not.
If no server is available for a queried domain, pdnsd will return an error
message to the client that usually will stop the clients attempts to resolve a
specific domain from this server (the libc resolver will e.g. return an error
to the application that tried to resolve the domain if no other servers are
available in the resolv.conf). This may be of use sometimes.
The default for this option is included.
iinncclluuddee==ssttrriinngg;;
This options adds an entry to the exclusion/inclusion list. If a domain matches
the name given as string, the server is queried if this was the first matching
rule (see also the entry for policy).
The domain name given must end in a dot. If it starts with a dot, the whole
subdomain of the given name including the one of that name is matched, e.g.
"foo.bar." will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case,
of course) will be matched (hint: if you want to include all subdomains, but
not the domain of the given name itself, place an exact-match exclude rule
before the include rule, e.g: exclude="foo.bar."; include=".foo.bar.";
eexxcclluuddee==ssttrriinngg;;
This options adds an entry to the exclusion/inclusion list. If a domain matches
the name given as string, the server is not queried if this was the first
matching rule (see also the entry for policy).
The domain name given must end in a dot. If it starts with a dot, the whole
subdomain of the given name including the one of that name is matched, e.g.
"foo.bar." will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case,
of course) will be matched (hint: if you want to exclude all subdomains, but
not the domain of the given name itself, place an exact-match include rule
before the exclude rule, e.g: include="foo.bar."; exclude=".foo.bar.";

******** 22..11..33 rrrr SSeeccttiioonn ********
Every rr section specifies a dns resource record that is stored locally. It
allows you to specify own dns records that are served by pdnsd in a limited
way. Only PTR, A and SOA records are implemented.
This option is intended to allow you to define RRs for 1.0.0.127.in-addr.arpa.
and localhost. (and perhaps even one or two hosts) without having to start an
extra named if your cached name servers do not serve those records. It is NNOOTT
intended and not capable to work as a full-featured name server.

nnaammee==ssttrriinngg;;
Specifies the name of the resource records, i.e. the domain name of the
resource the record describes. This option must be specified before any a, soa
or ptr records. Only absolute domain names (names ending in the root domain, in
dotted notation ending with a dot) are allowed. For this and all following
arguments that take domain names, you need to specify domain names in dotted
notation (example venera.isi.edu.). Do not forget the dot at the end!
oowwnneerr==ssttrriinngg;;
Specifies the name of the host pdnsd runs on and that is specified in dns
answers (specifically, nameserver records). Must be specified before any a, ptr
and soa entries.
ttttll==nnuummbbeerr;;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
aa==ssttrriinngg;;
Defines an A (host address) record. The argument is an IP in dotted notation.
pdnsd will serve this adrress for the hostname given in the name option.
ppttrr==ssttrriinngg;;
Defines a PTR (domain name pointer) record. The argument is a host name in
dotted notation (see name). The ptr record is for resolving adresses into
names. For example, if you want to have the adress 127.0.0.1 into localhost,
and localhost into 127.0.0.1, you need something like the following sections:
rr {
owner="localhost.";
name="localhost.";
a="127.0.0.1";
soa="localhost.","root.localhost.",42,86400,900,86400,86400;
}
rr {
owner="localhost.";
name="1.0.0.127.in-addr.arpa.";
ptr="localhost.";
soa="localhost.","root.localhost.",42,86400,900,86400,86400;
}
 The second section is for reverse resolving and uses the ptr option. There is
something special about the name in the second section: when a resolver wants
to get a hostname from an internet address, it composes an adress that is build
of the IP address in reverse byte order (1.0.0.127 instead of 127.0.0.1) where
each byte of the adress written as number constitutes a sub-domain under the
domain in-addr.arpa.
So, if you want to compose an adress for reverse resolving, take your ip in
dotted notation (eg 1.2.3.4), reverse the byte order (4.3.2.1) and append in-
addr.arpa. (4.3.2.1.in-addr.arpa.) Then, define an rr section giving this
address as name and the domain name corresponding to that ip in the ptr option.
ssooaa==ssttrriinngg,,ssttrriinngg,,nnuummbbeerr,,nnuummbbeerr,,nnuummbbeerr,,nnuummbbeerr,,nnuummbbeerr;;
This defines a soa (record source information) record. The first string is the
domain name of the server and should be equal to the name you specified as
owner.
The second string specifies the email address of the maintainer of the name
server. It is also specified as a domain name, so you will have to replace the
@ sign in the name with a dot (.) to get the name you have to specify here. The
next parameter (the first number) is the serial number of the record. You
should increment this number if you change the record.
The 4th parameter (the 2nd number) is the refresh timeout. It specifies after
what amount of time a caching server should attempt to refresh the cached
record.
The 5th parameter specifies a time after which a caching server should attempt
to refresh the record after a refresh failure.
The 6th parameter defines the timeout after which a cached record expires if it
has not been refreshed.
The 7th parameter is the ttl that is specified in every rr and should be the
same as given with the ttl option (if you do not specify a ttl, use the default
86400)
All time parameters must be specified in seconds.

******** 22..11..44 ssoouurrccee SSeeccttiioonn ********
Every source section allows you to let pdnsd read the records from a file in an
/etc/hosts-like format. pdnsd will generate records to resolve the entries
address from its host name and vice versa for every entry in the file. This is
normally easier than defining an rr for every of your addresses, since
localhost and your other FQDNs are normally given in /etc/hosts.
The accepted format is as follows: The #-sign initiates a comment, the rest of
the line from the first occurence of this character on is ignored. Empty lines
are tolerated.
The first entry on a line (predeceded by an arbitrary number of tabs and
spaces) is the IP in dotted notation, the second entry on one line (separated
by the first by an arbitrary number of tabs and spaces) is the FQDN (fully
qualified domain name) for that ip. The rest of the line is ignored (in the
original /etc/hosts, it may contain information not needed by pdnsd).

oowwnneerr==ssttrriinngg;;
Specifies the name of the host pdnsd runs on and that are specified in dns
answers (specifically, nameserver records). Must be specified before any file
entries.
Only absolute domain names (names ending in the root domain, in dotted notation
ending with a dot) are allowed. Example: venera.isi.edu.
ttttll==nnuummbbeerr;;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
ffiillee==ssttrriinngg;;
The string specifies a file name. For every file entry in a source section,
pdnsd will try to load the given file as described above. Failure is indicated
only when the file cannot be opened, malformed entries will be ignored.
sseerrvvee__aalliiaasseess==((oonn||ooffff));;
If this is turned on pdnsd will serve the aliases given in a hosts-style file.
These are the third entry in a line of a hosts-style file, which usually give a
"short name" for the host. This may be used to support broken clients without a
proper domain-search option. If no aliases are given in a line of the file,
pdnsd behaves as without this option for this line.
This feature was suggested by Bert Frederiks.
It is off by default.

********** 33 ppddnnssdd--ccttll **********
pdnsd-ctl allows you to run-time configure pdnsd. To make this work, you have
to start pdnsd with the -g option (or use the status_ctl option in the config
file). You also should make sure that you have appropriate permissions on the
control socket (use the ctl_perms option to make this sure).
The following table lists the command line options that pdnsd-ctl supports. The
command must always be the first option, the options to the command must follow
in the given order.
CCoommmmaanndd OOppttiioonnss                                            DDeessccrriippttiioonn
help                                                       print a help screen.
version                                                    print version info
                                                           Set the status of
                                                           the server with the
                                                           given index to up or
                                                           down, or force a
                                                           retest. The index is
                                                           assigned in the
                                                           order of definition
                                                           in pdnsd.cache
                                                           starting with 0. Use
server  index (<up>|<down>|<retest>)                       the status command
                                                           to view the indexes.
                                                           You can specify all
                                                           instead of an index
                                                           to perform th action
                                                           for all servers
                                                           registered with
                                                           pdnsd. Example:
                                                           pdnsd-ctl server 0
                                                           retest
                                                           Delete or invalidate
                                                           the record of the
                                                           given domain if it
                                                           is in the cache.
                                                           Invalidation means
                                                           that the record is
                                                           marked as timed out,
                                                           and such is reloaded
                                                           if possible (if
                                                           purge_cache is set
                                                           to on, it will be
                                                           deleted in any
                                                           case).
record  name  (<delete>|<invalidate>)                      For local records
                                                           (i.e., records that
                                                           were given in the
                                                           config file using a
                                                           rr section, records
                                                           read from a hosts-
                                                           style file and
                                                           records added using
                                                           pdnsd-ctl),
                                                           invalidation has no
                                                           effect. Deletion
                                                           will work, though.
                                                           Example:
                                                           pdnsd-ctl record
                                                           localhost. delete
                                                           Load a hosts-style
                                                           file. Works like
                                                           using the pdnsd
                                                           source option. Owner
                                                           and ttl are used as
                                                           in the source
                                                           section. ttl has a
                                                           default of 900 (it
                                                           does not need to be
                                                           specified). The last
                                                           option corresponds
source  fn    owner                   [ttl] [(<on>|<off>)] to the serve_aliases
                                                           option, and is off
                                                           by default (i.e. if
                                                           it is not
                                                           specified). fn is
                                                           the filename. The
                                                           file must be
                                                           readable by pdnsd!
                                                           Example:
                                                           pdnsd-ctl source /
                                                           etc/hosts localhost.
                                                           900 off
add     a     addr                    name  [ttl]          Add a record of the
add     aaaa  addr                    name  [ttl]          given type to the
add     ptr   host                    name  [ttl]          pdnsd cache,
                                                           replacing existing
                                                           records for the same
                                                           name and type. The
                                                           2nd argument
                                                           corresponds to the
                                                           argument of the
                                                           option in the rr
                                                           section that is
                                                           named like the first
                                                           option: a is a
                                                           record for hostname-
                                                           to-address mapping,
                                                           aaaa is the same
                                                           thing for IPv6
                                                           addresses, and ptr
                                                           is for address-to-
                                                           hostname mapping.
                                                           See the
add     cname host                    name  [ttl]          documentation for
                                                           the rr section for
                                                           more details. The
                                                           ttl is optional, the
                                                           default is 900
                                                           seconds. If you want
                                                           no other record than
                                                           the newly added in
                                                           the cache, do
                                                           pdnsdctl record
                                                           <name> delete before
                                                           adding records. This
                                                           is also better when
                                                           overwriting local
                                                           records. Example:
                                                           pdnsd-ctl add a
                                                           127.0.0.1 localhost.
                                                           900


********** 44 PPrroobblleemmss...... **********
If you have problems with configuring or tunning pdnsd, be sure to read th _F_A_Q.
If this does not help you, pdnsd crashes or you find bugs, please mail me at
_t_m_o_e_s_t_l_@_g_m_x_._n_e_t.

********** 55 HHaacckkiinngg **********
Here comes some information you might find useful for hacking on pdnsd.
******** 55..11 SSoouurrccee ffiilleess ********
Makefile.am, configure.in, acconfig.h autoconf/automake/autoheader scripts.
                                      Makefile.am's are in most subdirectories.
                                      A template from which configure generates
pdnsd.spec.in                         a spec file for building rpm's for
                                      various distributions.
version                               Contains only the program version string.
                                      Needed for several templates.
src/rc/*                              rc scripts for various linux
                                      distributions.
                                      The pdnsd cache subsystem(s) as defined
                                      in src/cacheing/cache.h. There is the
                                      "traditional" pdnsd system in the
src/cacheing/*                        subdirectory native. This system keeps
                                      the cache in memory and uses hash tables
                                      for accesses. Sourav K. Mandal is working
                                      on a system using gdbm.
                                      Contains the code for pdnsd-ctl, a
src/pdnsd-ctl/*                       program that allows to control pdnsd at
                                      run time.
                                      The lex/flex source file for the config
src/conf-lex.l.in                     file lexer. This is a template because
                                      there might be inserted "%option
                                      yylineno" for proper flex support.
                                      This is automatically generated by
src/conf-lex.l.                       configure from conf.l.templ. It may be
                                      overwritten in any make, so never modify
                                      this, but conf.l.templ instead!
src/conf-parse.y                      The yacc/bison source of the config file
                                      parser.
                                      The configuration handler functions and
src/conff.c, src/conff.h              their prototypes. The parser is called
                                      from here.
                                      Some constants used by lexer, parser,
src/consts.h                          config file handler functions and in the
                                      server status thread, among others.
                                      Define dns message structures, constants,
src/dns.c, src/dns.h                  and some common dns data handlers. dns.h
                                      contains gcc-specific code (in
                                      praticular, "__attribute__((packed))").
src/dns_answer.c, src/dns_answer.h    Define functions that answer incoming dns
                                      queries.
src/dns_query.c, src/dns_query.h      Define functions to manage outgoing dns
                                      queries.
src/error.c, src/error.h              Functions for error output to stderr or
                                      the syslog.
src/helpers.c, src/helpers.h          Define miscellaneous helper functions.
src/icmp.c, src/icmp.h                Define a function for performing a ping
                                      test. This contains OS-specific code.
                                      Contains main(), which holds the command
src/main.c                            line parser, performs initialisations and
                                      signal handling.
src/netdev.c, src/netdev.h            Define functions for network device
                                      handling. OS-specific.
                                      Define functions for the server status
src/servers.c, src/servers.h          thread that performs the periodical
                                      uptests.
                                      Define functions for the status control
src/status.c, src/status.h            thread. This is pdnsd's interface to
                                      pdnsd-ctl.

===============================================================================
     _T_h_o_m_a_s_ _M_o_e_s_t_l
$Id: doc.html,v 1.25 2000/10/19 16:38:31 thomas Exp $
