pdnsd Homepage pdnsd FAQ Documentation GNU GPL (pdnsd's License) Download Section

pdnsd Documentation

This is the "official" pdnsd documentation and reference written by Thomas Moestl with revisions by Paul Rombouts.
This manual is a part of the pdnsd package, and may be distributed in original or modified form under terms of the GNU General Public License, as published by the Free Software Foundation; either version 3, or (at your option) any later version.
You can find a copy of the GNU GPL in the file COPYING in the source or documentation directory.
This manual is up-to-date for version 1.2.8-par. For older documentation, please refer to the doc directory of the respective pdnsd package.
A somewhat outdated pdnsd HOWTO ("unofficial" step-by-step installation and setup instructions) is available at http://www.geocities.com/sunil_tt/. For Apple Mac users, Brian Wells has published a good HOWTO at http://web.mac.com/brianwells/main/pdnsd.html.

0. Installation

0.1 Installing binary RPM'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 adapt your configuration file (stored in /etc/pdnsd.conf) according to your needs (see below). In the Red Hat and SuSE RPMs, a start script is also installed; read the section 0.4, Start at Boot Time about that.

0.2 Building RPM's

It is possible to build a binary RPM from a source package using the command

rpmbuild --rebuild pdnsd-<version>.src.rpm

or alternatively from a tarball using the command

rpmbuild -tb pdnsd-<version>.tar.gz

You can do this as root, but it is safer to build a binary package first as a normal user, and then, when all has gone well, install the resulting binary package as root as in the previous section. How to build an RPM package without being root is described at http://www.ibm.com/developerworks/library/l-rpm2/.

Several pdnsd-specific options are available when building RPM packages:
--with isdn Has the same effect as --enable-isdn (see below).
--without poll Has the same effect as --disable-poll (see below).
--without nptl Has the same effect as --with-thread-lib=linuxthreads (see below).
--with ipv6 Has the same effect as --enable-ipv6 (see below).
--without tcpqueries Has the same effect as --disable-tcp-queries (see below).
--without debug Has the same effect as --with-debug=0 (see below).
--define "distro <distro>" Has the same effect as --with-distribution=<distro> (see below).
--define "run_as_user <user>" Has the same effect as --with-default-id=<user> (see below).
For RPMs the default <user> is "pdnsd".
--define "run_as_uid <uid>" If the user defined by the previous option does not exist when the RPM is installed, the pre-install script will try to create a new user with numerical id <uid>. The default is to let the system choose the numerical id at install time.
--define "cachedir <dir>" Has the same effect as --with-cachedir=<dir> (see below).
You can also configure which compiler flags will be used by setting the environment variable CFLAGS. Using a bash shell, you can do that on the command line like this:  CFLAGS="-O1 -Wall" rpmbuild ...
This is useful if you prefer a different level of optimization, for instance.

0.3 Installing from the pure sources (tar archives)

0.3.1 Decompressing

The pdsnsd source comes in a gzip'ed tar archive. To decompress it (using a modern tar) do

tar -xzf pdnsd-<version>.tar.gz

If your tar doesn't do this, use:

gzip -dc pdnsd-<version>.tar.gz | tar -xf -

0.3.2 Setup

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):
--prefix=dir Specify the prefix directory. The pdnsd files are installed in subdirectories of the prefix, the 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).
--sysconfdir=dir Specify the config directory. pdnsd expects its pdnsd.conf file to reside there if the -c option is not given at startup. The default for this is the etc subdirectory of your prefix, e.g. /usr/local/etc if you did not specify a prefix. To set this e.g. to /etc, use --sysconfdir=/etc.
--with-distribution=distro Specify target distribution (default=Generic; others: RedHat, SuSE, Debian)
See below for the effect of these settings.
--with-target=platform Change compilation target platform (default: autodetect; others: Linux, BSD, Cygwin).
autodetect will attempt to detect whether you are using Linux, *BSD or Cygwin and should normally be sufficient. If this does not work, try specifying your system manually (for the Darwin platform (Apple Mac OS X) specify BSD here).
--with-cachedir=dir Default directory for pdnsd cache (default=/var/cache/pdnsd)
This setting can be changed via config file settings when pdnsd has been built.
--with-hash-buckets=num Number of hash buckets to use (default=1024). The default should be sufficient for most purposes, but if you want to store a large number of names in the cache, cache lookups may be faster if the number of hash buckets is comparable to the number of names stored in the cache. The number actually used is the smallest power of two greater or equal to the number specified here.
--enable-isdn Enable ISDN support
This option will work only on Linux and may cause 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 Enable IPv6 networking support.
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-startup Enable IPV6 on pdnsd startup by default (default=IPv4). These options are only defaults, 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.
--disable-tcp-queries Disable TCP as query method. This only effects the querying of name servers by pdnsd, not the ability of pdnsd to answer TCP queries from clients. TCP queries are slower than UDP queries, but can be more secure against certain types of attacks and are able to handle large answers. For normal use this can be disabled. (Note that the default has changed: TCP-query support is now compiled in by default, but it still depends on the run-time options whether it is actually used.)
--with-query-method=qm Specify the query method (default=udponly, others: tcponly, tcpudp, udptcp). If you have enabled both UDP and TCP queries, this lets you control which query method pdnsd will use by default. tcpudp will try TCP first and fall back to UDP if TCP is not supported by the server; udptcp will try UDP first and, if the answer was truncated, will repeat the query using TCP. udponly and tcponly should be clear. Note that this only effects the compiled-in default; the query method can still be changed using command-line options or options in the configuration file.
--disable-tcp-server Disable the TCP server. In this case pdnsd will not be able to respond to TCP queries from clients. This may cause problems with very large answers.
--disable-src-addr-disc Disable the UDP source address discovery.
You need this only if you have trouble with messages saying "could not discover udp source address".
For the Cygwin target, this option is disabled by default.
--disable-poll Disable poll(2) and use select(2) (default=enabled)
You will normally not need this.
--disable-new-rrs Disable new DNS RR types. This may cause problems with some resolvers. The new types are RP, AFSDB, X25, ISDN, 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.
--enable-strict-rfc2181 Enforce strict RFC 2181 compliance.
This will cause pdnsd to reject DNS answers with incorrect timestamp settings (multiple RRs of the same type and for the same domain with different TTLs). Normally not needed.
--enable-underscores This option is obsolete. Since version 1.2, pdnsd places no restrictions on the types of characters in domain names (there are still a few restrictions for locally defined names, though).
--with-random-device=device Specify random device; default: C Library random() PRNG
pdnsd uses (pseudo-) random numbers as query IDs for security reasons (this makes forging DNS answers more difficult). This option controls where pdnsd gets these from. The default is the C library random() function, which is relatively weak. 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 - it is more secure, but may block and delay pdnsd's answers for a long time.
You can specify arc4random to use the BSD arc4random() library function (default for FreeBSD target), which is considered safe.
You can also specify random as device to use the C Library random() function (described above).
--with-default-id=user Specify default user for pdnsd (default=nobody). This is the user that will be entered for the 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.
--with-debug=level Specify debugging level. Normally you can safely switch debugging off by setting the level to 0. This will increase speed (although only marginally) and save space in the executable (only about 12kB). However, more significant may be the savings in stack space, especially if pdnsd is put under heavy load and there are many simultaneous running threads.
Presently the only defined debug levels are in the range 0 - 9. Setting the level to 9 enables hex dumps of the queries and replies pdnsd receives and should normally not be needed. Debug output will only be generated if you turn on special switches; it might be useful for debugging your config files, so I recommend using the default (1). However, if you use pdnsd under heavy load, a better strategy may be to compile one version of pdnsd without debug support (configured with --with-debug=0) for production use, and one version with with debug support (e.g. --with-debug=9) for diagnostic purposes.
--with-verbosity=level Specify default message verbosity. The default should be ok.
--enable-rcsids Enable RCS IDs in executables (default=disabled).
For personal use, there is no need to do this. If you build rpm's, it might have advantages.
--enable-tcp-subseq 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 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.
--with-tcp-qtimeout=secs Specify default tcp query timeout after which the connection is closed if no full query has been received. The default is 30s. You can also change this option at run time using the tcp_qtimeout config file option. If you do not use --enable-tcp-server, is option is not honored.
--with-par-queries=num Specify the default number of queries that can be executed in parallel. You can also change this option at run time using the 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.
--with-thread-lib=lib Added by Paul Rombouts: Use this option if you experience problems with signal handling under Linux. The usual symptom is that pdnsd fails to save the cache to disk, and /var/cache/pdnsd/pdnsd.cache remains empty. If you experience this kind of trouble, try reconfiguring with different values for the --with-thread-lib option. The allowable values are linuxthreads (or lt for short), linuxthreads2 (or lt2 for short), and nptl. By default the configure script tries to detect automatically whether linuxthreads or nptl is more appropriate for your system, but the method used is not foolproof. Look for the line: checking if this is an NPTL-based system...
If the automatic test mistakenly indentifies the thread library on your system as NPTL based, you should reconfigure with --with-thread-lib=lt and recompile. If the result of the automatic test is "no" or if --with-thread-lib=lt does not have the desired effect, try again using --with-thread-lib=lt2 .
Normally, you will need only --prefix, --sysconfdir and --with-distribution. If you specify your distribution using --with-distribution, this has the following effects: If you choose Generic, no rc script is installed, and a generic spec file is generated.
Further instructions are in the INSTALL document in the pdnsd source directory. ./configure --help will give you a list of all supported command line options.

Note added by Paul Rombouts: Some people may want change the compiler optimization flag. I use the -O2 flag, but it might be safer to use a lower level of optimization or no optimization at all. In that case prefix the configure command with the desired compiler flags like this (assuming you're using a bash shell):

CFLAGS="-O1 -Wall" ./configure ...


0.3.3 Building & installing

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.sample (a sample configuration) to the pdnsd config directory.
  4. creates your cache directory if it is not there. After installation, you should check the file permissions and create or 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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answer.
Setting the source address currently does not work for IPv4. I have written a kernel patch that will provide an easy way to program this. We'll see if or when it gets commited.


1 Invocation

When invoking pdnsd, you can specify various options at the command line. Command line options always override config file options. The various --noX options are present to override config file options.

pdnsd --help (or -h) gives you an overview of the pdnsd command line options.

pdnsd --version (or -V for short) prints licence and version information.

To start pdnsd as background daemon, specifiy --daemon (or -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. --nodaemon will disable this.

When starting pdnsd as a daemon, the -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 than /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging support, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in daemon mode, the messages will be written to the pdnsd.debug file in your cache directory. --nodebug disables debugging.

pdnsd -vn 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 or --status enables the status control socket. This is a named socket in the cache directory called pdnsd.status. This socket allows run-time configuration of pdnsd using the utility pdnsd-ctl. See below for more details about pdnsd-ctl. --nostatus disables status control. See also the configuration option status_ctl in the global section.

The option --notcp disables the seldom needed TCP server thread, which may save you some resources. -t or --tcp will enable it. See also the tcp_server configuration option.

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported (see also the query_method configuration option):
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the Internet.
-mto: 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.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.
-mut: New in version 1.2.5: pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated (i.e. the tc bit is set). This is the behaviour recommended by the DNS standards.

The -4 option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.
The -6 option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.
The -a option is only available when pdnsd was compiled with both IPv4 and IPv6 support. With this option, pdnsd will try to detect automatically if a system supports IPv6, and fall back to IPv4 otherwise.

With -i prefix or --ipv4_6_prefix=prefix you can set the prefix pdnsd uses (when running in IPv6 mode) to map IPv4 addresses in the configuration file to IPv6 addresses. There is also a corresponding option for the config file, see below. Must be a valid IPv6 address. The default is ::ffff:0.0.0.0

2 The configuration file

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.1 Layout

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, a number, a time specification or a constant. In previous versions of pdnsd strings had to be enclosed in quotes ("), but since version 1.1.10 this is no longer necessary, unless a string contains a special character such as whitespace, a token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-letter suffix. The following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w (weeks). If the suffix is missing, seconds are assumed. If several time specifications are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 + 30*60 = 9000 seconds.
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|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed 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.1.1 global Section

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:

perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 8 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.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd" (unless pdnsd was compiled with a different default).
server_port=number;
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.
server_ip=string;
or
interface=string;
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. For example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. The default setting for this option is server_ip=any, which means that pdnsd will listen on all of your local interfaces. Presently you can only specify one address here; if you want pdnsd to listen on multiple interfaces but not all you will have to specify server_ip=any and use firewall rules to restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by default, you will need to use the -6 command-line option or set run_ipv4=off first (see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or "eth0" here, instead of an IP address (this has been tested on Linux, and may or may not work on other platforms). pdnsd will not bind to the interface name, but will look up the address of the interface at start-up >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!
Security notes: never 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.3.4 Manual installation

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); Permissions should be at max rwxr-xr-x (if you want to protect your cache and status socket, make it rwx------).
Thats it!

0.4 Start at boot time

In the src/rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE, Redhat and Debian Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently it must be installed manually. See src/rc/README and src/rc/Slackware/rc.pdnsd for details.

0.4.1 SuSE Linux startup

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:
manual installation
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 COPYING 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.4.2 Red Hat Linux startup

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:
manual installation
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 COPYING. 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.5 Notes for FreeBSD users

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. In seldom cases, this will not be the case, because the kernel selects the source address depending on the interface that was used for sending the answe