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

pdnsd Documentation

This is the "official" pdnsd documentation and reference.
It is up-to-date for version 1.1.0b1. For older documentation, please refer to the doc directory of the respective pdnsd package.
A pdnsd HOWTO ("unofficial" step-by-step installation and setup instructions) is available at http://www.geocities.com/sunil_tt/.

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

0.2 Installing source RPM's

To install a source RPM, just do
rpm --recompile pdnsd-<version>.rpm
This should install pretty much everything automatically. The only thing left for you to do is adapt your configuration file (stored in /etc/pdnsd.conf) according to your needs. In the SuSE RPMs, a start script is also installed; read the section Start at Boot Time about that.

0.3 Installing from the pure sources (tar archives)

0.3.1 Decompressing

pdsnsd comes in two different packed archives: the standard gzip'ed version pdnsd-<version>.tar.gz, and the bzip2-packed version (about 10% smaller) pdnsd-<version>.tar.bz2. If you have bunzip2 installed on your computer, I recommed you save bandwidth and get the .bz2-version. To decompress it (using a modern tar) do
tar -xzf pdnsd-<version>.tar.gz
--or--
tar -xIf pdnsd-<version>.tar.bz2

If your tar doesn't do this, use:
gunzip pdnsd-<version>.tar.gz
tar -xf pdnsd-<version>.tar
--or--
bunzip2 pdnsd-<version>.tar.bz2
tar -xf pdnsd-<version>.tar

0.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)
autodetect will attempt to detect whether you are using *BSD or Linux and should normally be sufficient. If this does not work, try specifyning you system manually.
--with-cachedir=dir Default directory for pdnsd cache (default=/var/cache/pdnsd)
This setting can be changed via config file settings when pdnsd was built.
--with-dbm=dbm Specifiy database manager to use for cacheing (default=native; others: gdbm)
Currently, only native will work.
--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.
--enable-tcp-queries Enable the TCP as query method. This is seldom needed in normal usage.
--with-query-method=qm Specify the query method (default=udponly, others: tcpudp, tcponly) If you have enabled both udp and tcp queries, this lets you control which query method pdnsd will use ny default. tcpudp will try tcp first and back out to udp if tcp is not supported by the server; udponly and tcponly should be clear.
--disable-tcp-server Disable tcp server. 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".
--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 Allow underscores (_) in domain names. This breaks RFC compliance, but some sites use it for historical reasons because BIND used to support it.
--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. Debug output will only be generated if you turn on special switches; it might be useful for debugginh your config files, so I recommend using the default (9).
--with-verbosity=level Specify default message verbosity. The default should be ok.
--enable-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 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 th tcp_qtimeout config file option. If you do not use --enable-tcp-server, is option is not honored.
--with-par-queries Specify the default number of queries that can be executed in parallel. You can also change this option at run time using th par_queries config file option. See the description of that option for an explanation of what it really does.
The default for this option is 2.
Normally, you will need only --prefix, --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 installled, and a generic spec file is generated.
Further instructions are in the INSTALL document in the pdsd source directory. ./configure --help will give you a list of all supported command line options.

0.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); Permisions 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 rc folder of the pdnsd distribution are start scripts for pdnsd designed for different Linux distros. There are scripts for SuSE and Redhat Linux now.
The start scripts are automatically installed during RPM install, and also during make install if you specified your distro.

0.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 dependig 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 that /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.

If pdnsd was compiled with debugging options enabled, you may specify -g or --debug on the command line. This will cause extra diagnostic messages to be printed. When pdnsd runs in deamon mode, the messages will be written to the pdnsd.debug file in your cache directory. --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 pipe. This is a named pipe in the server directory called status. You can read the server status by doing
cat <your cache directory>/status. --nostatus disables the status pipe.

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

Using the -m option, you can select the method pdnsd uses to query other name servers. Following methods are supported:
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers on the internt.
-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.

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 (enclosed in "), a number or a constant. Constants are noted in the section description in <> signs, but are written in the file without these signs. Some options take more than one value; in this case, the values are separated with commas.
If you may supply one of a set of possible values to an option, this is noted in the documentation as
(option1|option2|option3|...)
Comments may be onclosed in /* and */, nested comments are possible. If the # sign or two slashes (//) appear in the configuration file, everything from these signs to the end of the current line is regarded as a comment and ignored.
There are examples for nearly all options in the sample config file.

2.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, 4 bytes will still be written to disk. The memory cache is always 10kB larger than the file cache. This value is 2048 (2 MB) by default.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd".
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;
Set the ip address pdnsd listens on for requests. This can be useful when the host has several interfaces and you want pdnsd not to listen on all interfaces. Addtionally, it is possibly to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. pdnsd will listen on all of your local interfaces by default. The ip is treated as string and therefore needs to have quotation marks around it.
linkdown_kluge=(<on>|<off>);
This option enables a kluge that some people might need: when all servers are marked down, with this option set the cache is not even used when a query is received, and a DNS error is returned in any case. The only exception from this is that local records (as specified in rr and source sections are still served normally. In general, you probably want to get cached entries even when the network is down, so this defaults to off.
max_ttl=number;
This options sets the maximum time a record is hold in cache in seconds. All dns resource records have a time to live field that says for what period of time the record may be cached before it needs to be requeried. If this is more than the value given with max_ttl, this time to live value is set to max_ttl. This is done to prevent records from being cached an inappropriate long period of time, because that is almost never a good thing to do. Default is 604800s (one week).
min_ttl=number;
This options sets the minimum time a record is hold in cache in seconds. All dns resource records have a time to live field that says for what period of time the record may be cached before it needs to be requeried. If this is less than the value given with min_ttl, this time to live value is set to min_ttl. Default is 120 seconds.
neg_ttl=number;
This option sets the time that negative cached records will remain valid in the cache if no time to live can be determined. This is always the case when whole domains are being cached negative, and additionally when record types are cached negative for a domain for which no SOA record is known to pdnsd. If a SOA is present, the ttl of the SOA is taken.
neg_rrs_pol=(<on>|<off>|<auth>);
This sets the RR set policy for negative cacheing; this tells pdnsd under which circumstances it should cache a record type negative for a certain domain. off will turn the negative cacheing of record types off, on will always add a negative cache entry when a name server did not return a record type we asked it for, and auth will only add such entries if the answer came from an authoritative name server for that domain. The preset is auth. This is normally the right thing, as some cacheing servers behave strange.
neg_domain_pol=(<on>|<off>|<auth>);
This is analogue to neg_rrs_pol for whole domain negative cacheing. The preset is on here, because I have not seen a cacheing server that will falsely claim that a domain does not exist. If you experience problems with false negatives, try setting this to auth.
run_as=string;
This option allows you to let pdnsd change its user and group id after operations that needed privileges have been done. This helps minimize security risks and is therefore recommended. The supplied string gives a user name whose user id and primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if specified) and starting the server status thread, the main thread changes its gid and uid, as do all newly created threads thereafter. By taking another uid and gid, those threads run with the privileges of the specified user. Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option is set to off (see below, on by default), because these may be needed for exec uptests. The manager thread also retains its original privileges in this case. You should take care that the user you specify has write permissions on your cache file and status pipe (if you need a status pipe). You should look out for error messages like "permission denied" and "operation not permitted" to discover permission problems.
strict_setuid=(<on>|<off>);
When used together with the run_as option, this option lets you specify that all threads of the program will run with the privileges of the run_as user. This provides higher security than the normal run_as option, but is not always possible. See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(<on>|<off>);
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to query other servers themselves if possible, and to give back answers for domains that may not be in its authority), and accepts additional records with information for servers that are not in the authority of the queried server. This opens the possibility of so-called cache poisoning: a malicious attacker might set up a dns server that, when queried, returns forged additional records. This way, he might replace trusted servers with his own ones by making your dns server return bad IP addresses. This option protects you from cache poisoning by rejecting additional records that do not describe domains in the queried servers authority space and not doing recursive queries any more. An exception to this rule are the servers you specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same operation.
You should also notice that there may be other similar security problems, which are essentially problems of the DNS, i.e. any "traditional" server has them (the DNS security extensions solve these problems, but are not widely supported). One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a query you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet count of 32768 is needed for that attack). pdnsd can use TCP for queries, which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network traffic, this attack is relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP).
The paranoid option is off by default.
scheme_file=string;
In addition to normal uptests, you may specify that some servers shall only be queried when a certain pcmcia-cs scheme is active (only under linux). For that, pdnsd needs to know where the file resides that holds the pcmcia scheme information. Normally, this is either /var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.
status_ctl=(<on>|<off>);
This has the same effect as the -s command line option: the status control is enabled when on is specified.
daemon=(<on>|<off>);
This has the same effect as the -d command line option: the daemon mode enabled when on is specified.
tcp_server=(<on>|<off>);
This has the same effect as the -t command line option: the tcp serving ability is enabled when on is specified.
pid_file=string;
This has the same effect as the -p command line option: you can specify a file that pdnsd will write its pid into when it starts in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can set the verbosity of pdnsd's messages with it. The argument is a number between 0 (few messages) to 3 (most messages).
query_method=(<tcp_only>|<udp_only>|<tcp_udp>);
This has the same effect as the -m command line option. Read the documentation for the command line option on this. tcp_only corresponds to the to, udp_only to the uo and tcp_udp to the tu argument of the command line option.
run_ipv4=(<on>|<off>);
This has the same effect as the -4 command line option: if on is specified, IPv4 support is enabled, and IPv6 support is disabled (if available). ff off is specified, IPv4 will be disabled and IPv6 will be enabled. You can only use this option if you have compiled pdnsd with IPv4 as well as with IPv6 support.
debug=(<on>|<off>);
This has the same effect as the -g command line option: the debugging messages are enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the pdnsd status control socket will have. These are the same as file permissions. The owner of the file will be the run_as user, or, if none is specified, the user who started pdnsd. If you want to specify the permissions in octal (as usual), don't forget the leading zero (0600 instead of 600!). To use the status control, write access is needed. The default is 0600 (only the owner may read or write).
Please note that the socket is kept in the cache directory, and that the cache directory permissions might also need to be adjusted. Please ensure that the cache directory is not writeable for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that will be active simultaneously. If this number is exceeded, queries are queued and may be delayed some time. See also the procq_limit option.
The default for this option are 20 query threads will be active (plus 3 to 6 threads that will always be present depending on your configuration).
procq_limit=number;
When the query thread limit is exceeded, connection attempts to pdnsd will be queued. With this option, you can set the maximum queue length. If this length is also exceeded, the incoming queries will be dropped. That means that tcp connections will be closed and udp queries will just be dropped, which will probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option.
The default for this option is 30.
tcp_qtimeout=number;
This option sets a timeout for tcp queries. If no full query has been received on a tcp connection after that time has passed, the connection will be closed. The default is set using the --with-tcp-qtimeout option to configure.
par_queries=number;
This option sets the maximum number of queries that will be executed in parallel, i.e. how many servers are simultaneously queried. This may speed up the query process if there are very slow servers to be quered (the first answer we get will be taken), but it will also increase network and server load. 1 or 2 are good values for this option. The default is set using the --with-par-queries option to configure.
randomize_recs=(<on>|<off>);
If this option is turned on, pdnsd will randomly reorder the cached records of one type when creating an answer. This supports round-robin DNS schemes and increases fail safety for hosts with multiple IP addresses, so this is usually a good idea,
On by default.
query_port_start=number;
If given, defines the start of the port range used for queries of pdnsd. The value given must be >= 1024. The purpose of this option is to aid certain firewall configurations that are based on the source port. Please keep in mind that another application may bind a port in that range, so a stateful firewall using target port and/or process uid may be more effective. In case a query start port is given pdnsd uses this port as the first port of a specified port range (see query_port_end) used for queries. pdnsd will try to randomly select a free port from this range as local port for the query.
To ensure that there are enough ports for pdnsd to use, the range between query_port_start and query_port_end should be adjusted to at least (par_queries * proc_limit). A higher value is highly recommended, because other applications may also allocate ports in that range. If possible, this range should be kept out of the space that other applications usually use.
query_port_end=number;
Only used if query_port_start is given. Defines the last port of the range started by query_port_start used for querys by pdnsd. The default is 65535, which is also the maximum legal value for this option. For details see the description of query_port_start.

2.1.2 server Section

Each server section specifies a name server that pdnsd should try to get resource records or authoritative name server information from. The servers a queried in the order of their appearance (or parallel to a limited extend). If one fails, the next one is taken and so on.
You probably want to specify the dns server in your LAN, the caching dns server of your internet provider or even one of the root servers using server records.
The supported options in this section are:

ip=string;
Give the ip (the ip, _not_ the hostname) of the server. Must be specified.
port=number;
Give the port the remwills user and group id after operations that needed privileges have been done. This helps minimize security risks and is therefore recommended. The supplied string gives a user name whose user id and primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if specified) and starting the server status thread, the main thread changes its gid and uid, as do all newly created threads thereafter. By taking another uid and gid, those threads run with the privileges of the specified user. Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option is set to off (see below, on by default), because these may be needed for exec uptests. The manager thread also retains its original privileges in this case. You should take care that the user you specify has write permissions on your cache file and status pipe (if you need a status pipe). You should look out for error messages like "permission denied" and "operation not permitted" to discover permission problems.
strict_setuid=(<on>|<off>);
When used together with the run_as option, this option lets you specify that all threads of the program will run with the privileges of the run_as user. This provides higher security than the normal run_as option, but is not always possible. See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(<on>|<off>);
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to query other servers themselves if possible, and to give back answers for domains that may not be in its authority), and accepts additional records with information for servers that are not in the authority of the queried server. This opens the possibility of so-called cache poisoning: a malicious attacker might set up a dns server that, when queried, returns forged additional records. This way, he might replace trusted servers with his own ones by making your dns server return bad IP addresses. This option protects you from cache poisoning by rejecting additional records that do not describe domains in the queried servers authority space and not doing recursive queries any more. An exception to this rule are the servers you specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same operation.
You should also notice that there may be other similar security problems, which are essentially problems of the DNS, i.e. any "traditional" server has them (the DNS security extensions solve these problems, but are not widely supported). One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a query you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet count of 32768 is needed for that attack). pdnsd can use TCP for queries, which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network traffic, this attack is relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP).
The paranoid option is off by default.
scheme_file=string;
In addition to normal uptests, you may specify that some servers shall only be queried when a certain pcmcia-cs scheme is active (only under linux). For that, pdnsd needs to know where the file resides that holds the pcmcia scheme information. Normally, this is either /var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.
status_ctl=(<on>|<off>);
This has the same effect as the -s command line option: the status control is enabled when on is specified.
daemon=(<on>|<off>);
This has the same effect as the -d command line option: the daemon mode enabled when on is specified.
tcp_server=(<on>|<off>);
This has the same effect as the -t command line option: the tcp serving ability is enabled when on is specified.
pid_file=string;
This has the same effect as the -p command line option: you can specify a file that pdnsd will write its pid into when it starts in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can set the verbosity of pdnsd's messages with it. The argument is a number between 0 (few messages) to 3 (most messages).
query_method=(<tcp_only>|<udp_only>|<tcp_udp>);
This has the same effect as the -m command line option. Read the documentation for the command line option on this. tcp_only corresponds to the to, udp_only to the uo and tcp_udp to the tu argument of the command line option.
run_ipv4=(<on>|<off>);
This has the same effect as the -4 command line option: if on is specified, IPv4 support is enabled, and IPv6 support is disabled (if available). ff off is specified, IPv4 will be disabled and IPv6 will be enabled. You can only use this option if you have compiled pdnsd with IPv4 as well as with IPv6 support.
debug=(<on>|<off>);
This has the same effect as the -g command line option: the debugging messages are enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the pdnsd status control socket will have. These are the same as file permissions. The owner of the file will be the run_as user, or, if none is specified, the user who started pdnsd. If you want to specify the permissions in octal (as usual), don't forget the leading zero (0600 instead of 600!). To use the status control, write access is needed. The default is 0600 (only the owner may read or write).
Please note that the socket is kept in the cache directory, and that the cache directory permissions might also need to be adjusted. Please ensure that the cache directory is not writeable for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that will be active simultaneously. If this number is exceeded, queries are queued and may be delayed some time. See also the procq_limit option.
The default for this option are 20 query threads will be active (plus 3 to 6 threads that will always be present depending on your configuration).
procq_limit=number;
When the query thread limit is exceeded, connection attempts to pdnsd will be queued. With this option, you can set the maximum queue length. If this length is also exceeded, the incoming queries will be dropped. That means that tcp connections will be closed and udp queries will just be dropped, which will probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option.
The default for this option is 30.
tcp_qtimeout=number;
This option sets a timeout for tcp queries. If no full query has been received on a tcp connection after that time has passed, the connection will be closed. The default is set using the --with-tcp-qtimeout option to configure.
par_queries=number;
This option sets the maximum number of queries that will be executed in parallel, i.e. how many servers are simultaneously queried. This may speed up the query process if there are very slow servers to be quered (the first answer we get will be taken), but it will also increase network and server load. 1 or 2 are good values for this option. The default is set using the --with-par-queries option to configure.
randomize_recs=(<on>|<off>);
If this option is turned on, pdnsd will randomly reorder the cached records of one type when creating an answer. This supports round-robin DNS schemes and increases fail safety for hosts with multiple IP addresses, so this is usually a good idea,
On by default.
query_port_start=number;
If given, defines the start of the port range used for queries of pdnsd. The value given must be >= 1024. The purpose of this option is to aid certain firewall configurations that are based on the source port. Please keep in mind that another application may bind a port in that range, so a stateful firewall using target port and/or process uid may be more effective. In case a query start port is given pdnsd uses this port as the first port of a specified port range (see query_port_end) used for queries. pdnsd will try to randomly select a free port from this range as local port for the query.
To ensure that there are enough ports for pdnsd to use, the range between query_port_start and query_port_end should be adjusted to at least (par_queries * proc_limit). A higher value is highly recommended, because other applications may also allocate ports in that range. If possible, this range should be kept out of the space that other applications usually use.
query_port_end=number;
Only used if query_port_start is given. Defines the last port of the range started by query_port_start used for querys by pdnsd. The default is 65535, which is also the maximum legal value for this option. For details see the description of query_port_start.

2.1.2 server Section

Each server section specifies a name server that pdnsd should try to get resource records or authoritative name server information from. The servers a queried in the order of their appearance (or parallel to a limited extend). If one fails, the next one is taken and so on.
You probably want to specify the dns server in your LAN, the caching dns server of your internet provider or even one of the root servers using server records.
The supported options in this section are:

ip=string;
Give the ip (the ip, _not_ the hostname) of the server. Must be specified.
port=number;
Give the port the remwills user and group id after operations that needed privileges have been done. This helps minimize security risks and is therefore recommended. The supplied string gives a user name whose user id and primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if specified) and starting the server status thread, the main thread changes its gid and uid, as do all newly created threads thereafter. By taking another uid and gid, those threads run with the privileges of the specified user. Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option is set to off (see below, on by default), because these may be needed for exec uptests. The manager thread also retains its original privileges in this case. You should take care that the user you specify has write permissions on your cache file and status pipe (if you need a status pipe). You should look out for error messages like "permission denied" and "operation not permitted" to discover permission problems.
strict_setuid=(<on>|<off>);
When used together with the run_as option, this option lets you specify that all threads of the program will run with the privileges of the run_as user. This provides higher security than the normal run_as option, but is not always possible. See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(<on>|<off>);
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to query other servers themselves if possible, and to give back answers for domains that may not be in its authority), and accepts additional records with information for servers that are not in the authority of the queried server. This opens the possibility of so-called cache poisoning: a malicious attacker might set up a dns server that, when queried, returns forged additional records. This way, he might replace trusted servers with his own ones by making your dns server return bad IP addresses. This option protects you from cache poisoning by rejecting additional records that do not describe domains in the queried servers authority space and not doing recursive queries any more. An exception to this rule are the servers you specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same operation.
You should also notice that there may be other similar security problems, which are essentially problems of the DNS, i.e. any "traditional" server has them (the DNS security extensions solve these problems, but are not widely supported). One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a query you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet count of 32768 is needed for that attack). pdnsd can use TCP for queries, which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network traffic, this attack is relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP).
The paranoid option is off by default.
scheme_file=string;
In addition to normal uptests, you may specify that some servers shall only be queried when a certain pcmcia-cs scheme is active (only under linux). For that, pdnsd needs to know where the file resides that holds the pcmcia scheme information. Normally, this is either /var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.
status_ctl=(<on>|<off>);
This has the same effect as the -s command line option: the status control is enabled when on is specified.
daemon=(<on>|<off>);
This has the same effect as the -d command line option: the daemon mode enabled when on is specified.
tcp_server=(<on>|<off>);
This has the same effect as the -t command line option: the tcp serving ability is enabled when on is specified.
pid_file=string;
This has the same effect as the -p command line option: you can specify a file that pdnsd will write its pid into when it starts in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can set the verbosity of pdnsd's messages with it. The argument is a number between 0 (few messages) to 3 (most messages).
query_method=(<tcp_only>|<udp_only>|<tcp_udp>);
This has the same effect as the -m command line option. Read the documentation for the command line option on this. tcp_only corresponds to the to, udp_only to the uo and tcp_udp to the tu argument of the command line option.
run_ipv4=(<on>|<off>);
This has the same effect as the -4 command line option: if on is specified, IPv4 support is enabled, and IPv6 support is disabled (if available). ff off is specified, IPv4 will be disabled and IPv6 will be enabled. You can only use this option if you have compiled pdnsd with IPv4 as well as with IPv6 support.
debug=(<on>|<off>);
This has the same effect as the -g command line option: the debugging messages are enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the pdnsd status control socket will have. These are the same as file permissions. The owner of the file will be the run_as user, or, if none is specified, the user who started pdnsd. If you want to specify the permissions in octal (as usual), don't forget the leading zero (0600 instead of 600!). To use the status control, write access is needed. The default is 0600 (only the owner may read or write).
Please note that the socket is kept in the cache directory, and that the cache directory permissions might also need to be adjusted. Please ensure that the cache directory is not writeable for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that will be active simultaneously. If this number is exceeded, queries are queued and may be delayed some time. See also the procq_limit option.
The default for this option are 20 query threads will be active (plus 3 to 6 threads that will always be present depending on your configuration).
procq_limit=number;
When the query thread limit is exceeded, connection attempts to pdnsd will be queued. With this option, you can set the maximum queue length. If this length is also exceeded, the incoming queries will be dropped. That means that tcp connections will be closed and udp queries will just be dropped, which will probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option.
The default for this option is 30.
tcp_qtimeout=number;
This option sets a timeout for tcp queries. If no full query has been received on a tcp connection after that time has passed, the connection will be closed. The default is set using the --with-tcp-qtimeout option to configure.
par_queries=number;
This option sets the maximum number of queries that will be executed in parallel, i.e. how many servers are simultaneously queried. This may speed up the query process if there are very slow servers to be quered (the first answer we get will be taken), but it will also increase network and server load. 1 or 2 are good values for this option. The default is set using the --with-par-queries option to configure.
randomize_recs=(<on>|<off>);
If this option is turned on, pdnsd will randomly reorder the cached records of one type when creating an answer. This supports round-robin DNS schemes and increases fail safety for hosts with multiple IP addresses, so this is usually a good idea,
On by default.
query_port_start=number;
If given, defines the start of the port range used for queries of pdnsd. The value given must be >= 1024. The purpose of this option is to aid certain firewall configurations that are based on the source port. Please keep in mind that another application may bind a port in that range, so a stateful firewall using target port and/or process uid may be more effective. In case a query start port is given pdnsd uses this port as the first port of a specified port range (see query_port_end) used for queries. pdnsd will try to randomly select a free port from this range as local port for the query.
To ensure that there are enough ports for pdnsd to use, the range between query_port_start and query_port_end should be adjusted to at least (par_queries * proc_limit). A higher value is highly recommended, because other applications may also allocate ports in that range. If possible, this range should be kept out of the space that other applications usually use.
query_port_end=number;
Only used if query_port_start is given. Defines the last port of the range started by query_port_start used for querys by pdnsd. The default is 65535, which is also the maximum legal value for this option. For details see the description of query_port_start.

2.1.2 server Section

Each server section specifies a name server that pdnsd should try to get resource records or authoritative name server information from. The servers a queried in the order of their appearance (or parallel to a limited extend). If one fails, the next one is taken and so on.
You probably want to specify the dns server in your LAN, the caching dns server of your internet provider or even one of the root servers using server records.
The supported options in this section are:

ip=string;
Give the ip (the ip, _not_ the hostname) of the server. Must be specified.
port=number;
Give the port the remwills user and group id after operations that needed privileges have been done. This helps minimize security risks and is therefore recommended. The supplied string gives a user name whose user id and primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if specified) and starting the server status thread, the main thread changes its gid and uid, as do all newly created threads thereafter. By taking another uid and gid, those threads run with the privileges of the specified user. Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option is set to off (see below, on by default), because these may be needed for exec uptests. The manager thread also retains its original privileges in this case. You should take care that the user you specify has write permissions on your cache file and status pipe (if you need a status pipe). You should look out for error messages like "permission denied" and "operation not permitted" to discover permission problems.
strict_setuid=(<on>|<off>);
When used together with the run_as option, this option lets you specify that all threads of the program will run with the privileges of the run_as user. This provides higher security than the normal run_as option, but is not always possible. See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(<on>|<off>);
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to query other servers themselves if possible, and to give back answers for domains that may not be in its authority), and accepts additional records with information for servers that are not in the authority of the queried server. This opens the possibility of so-called cache poisoning: a malicious attacker might set up a dns server that, when queried, returns forged additional records. This way, he might replace trusted servers with his own ones by making your dns server return bad IP addresses. This option protects you from cache poisoning by rejecting additional records that do not describe domains in the queried servers authority space and not doing recursive queries any more. An exception to this rule are the servers you specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same operation.
You should also notice that there may be other similar security problems, which are essentially problems of the DNS, i.e. any "traditional" server has them (the DNS security extensions solve these problems, but are not widely supported). One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a query you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet count of 32768 is needed for that attack). pdnsd can use TCP for queries, which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network traffic, this attack is relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP).
The paranoid option is off by default.
scheme_file=string;
In addition to normal uptests, you may specify that some servers shall only be queried when a certain pcmcia-cs scheme is active (only under linux). For that, pdnsd needs to know where the file resides that holds the pcmcia scheme information. Normally, this is either /var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.
status_ctl=(<on>|<off>);
This has the same effect as the -s command line option: the status control is enabled when on is specified.
daemon=(<on>|<off>);
This has the same effect as the -d command line option: the daemon mode enabled when on is specified.
tcp_server=(<on>|<off>);
This has the same effect as the -t command line option: the tcp serving ability is enabled when on is specified.
pid_file=string;
This has the same effect as the -p command line option: you can specify a file that pdnsd will write its pid into when it starts in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can set the verbosity of pdnsd's messages with it. The argument is a number between 0 (few messages) to 3 (most messages).
query_method=(<tcp_only>|<udp_only>|<tcp_udp>);
This has the same effect as the -m command line option. Read the documentation for the command line option on this. tcp_only corresponds to the to, udp_only to the uo and tcp_udp to the tu argument of the command line option.
run_ipv4=(<on>|<off>);
This has the same effect as the -4 command line option: if on is specified, IPv4 support is enabled, and IPv6 support is disabled (if available). ff off is specified, IPv4 will be disabled and IPv6 will be enabled. You can only use this option if you have compiled pdnsd with IPv4 as well as with IPv6 support.
debug=(<on>|<off>);
This has the same effect as the -g command line option: the debugging messages are enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the pdnsd status control socket will have. These are the same as file permissions. The owner of the file will be the run_as user, or, if none is specified, the user who started pdnsd. If you want to specify the permissions in octal (as usual), don't forget the leading zero (0600 instead of 600!). To use the status control, write access is needed. The default is 0600 (only the owner may read or write).
Please note that the socket is kept in the cache directory, and that the cache directory permissions might also need to be adjusted. Please ensure that the cache directory is not writeable for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that will be active simultaneously. If this number is exceeded, queries are queued and may be delayed some time. See also the procq_limit option.
The default for this option are 20 query threads will be active (plus 3 to 6 threads that will always be present depending on your configuration).
procq_limit=number;
When the query thread limit is exceeded, connection attempts to pdnsd will be queued. With this option, you can set the maximum queue length. If this length is also exceeded, the incoming queries will be dropped. That means that tcp connections will be closed and udp queries will just be dropped, which will probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option.
The default for this option is 30.
tcp_qtimeout=number;
This option sets a timeout for tcp queries. If no full query has been received on a tcp connection after that time has passed, the connection will be closed. The default is set using the --with-tcp-qtimeout option to configure.
par_queries=number;
This option sets the maximum number of queries that will be executed in parallel, i.e. how many servers are simultaneously queried. This may speed up the query process if there are very slow servers to be quered (the first answer we get will be taken), but it will also increase network and server load. 1 or 2 are good values for this option. The default is set using the --with-par-queries option to configure.
randomize_recs=(<on>|<off>);
If this option is turned on, pdnsd will randomly reorder the cached records of one type when creating an answer. This supports round-robin DNS schemes and increases fail safety for hosts with multiple IP addresses, so this is usually a good idea,
On by default.
query_port_start=number;
If given, defines the start of the port range used for queries of pdnsd. The value given must be >= 1024. The purpose of this option is to aid certain firewall configurations that are based on the source port. Please keep in mind that another application may bind a port in that range, so a stateful firewall using target port and/or process uid may be more effective. In case a query start port is given pdnsd uses this port as the first port of a specified port range (see query_port_end) used for queries. pdnsd will try to randomly select a free port from this range as local port for the query.
To ensure that there are enough ports for pdnsd to use, the range between query_port_start and query_port_end should be adjusted to at least (par_queries * proc_limit). A higher value is highly recommended, because other applications may also allocate ports in that range. If possible, this range should be kept out of the space that other applications usually use.
query_port_end=number;
Only used if query_port_start is given. Defines the last port of the range started by query_port_start used for querys by pdnsd. The default is 65535, which is also the maximum legal value for this option. For details see the description of query_port_start.

2.1.2 server Section

Each server section specifies a name server that pdnsd should try to get resource records or authoritative name server information from. The servers a queried in the order of their appearance (or parallel t