pdnsd Documentation

0. Installation

0.1 Installing binary RPM's

rpm -i pdnsd-<version>.rpm

0.2 Building RPM's

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

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

0.3 Installing from pure sources (tar archives or git repositories)

0.3.1 Setting up the source code tree

0.3.1.1 Unpacking a tar archive

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

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

0.3.1.2 Cloning a git repository

git clone git://gitorious.org/pdnsd/pdnsd.git pdnsd

0.3.2 Configuring the source

• An rc script is copied in the appropriate localtion, which enables pdnsd to start at machine boot time (see 0.4)
• Distribution-specific portions might be included in the generated pdnsd.spec file (only important if you want to build rpm archives yourself).

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

0.3.3 Building & installing

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!

0.3.4 Manual installation

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------).

0.4 Start at boot time

0.4.1 SuSE Linux startup

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.

0.4.2 Red Hat Linux startup

0.5 Notes for FreeBSD users

1 Invocation

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 is normally a digit from 0 to 3, where 0 means normal operation, while 3 will most verbose. Level 9 can be used in combination with the --debug option for very extensive debug information.
Note: The current implementation mostly ignores the verbosity level, so you may not notice much difference between the various levels.

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

2.1 Layout

2.1.1 global Section

2.1.2 server Section

2.1.3 rr Section

    rr {
	name = mydomain;
	ns = localhost;
	soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
    }
    rr {
	name = *.mydomain;
	a = 192.168.1.10;
    }

    rr {
	name = localhost;
	a = 127.0.0.1;
	owner = localhost;
	soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
    }
    rr {
	name = 1.0.0.127.in-addr.arpa;
	ptr = localhost;
	owner = localhost;
	soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
    }

    rr {
	name = news;
	cname = nntp2.myisp.com;
	owner = localhost;
    }

2.1.4 neg Section

    neg {
	name = news;
	types = domain;
    }
    neg {
	name = mail;
	types = domain;
    }

2.1.5 source Section

2.1.6 include Section

3 pdnsd-ctl

pdnsd-ctl allows you to configure pdnsd at run time. To make this work, you have to start pdnsd with the -s option (or use the status_ctl option in the config file). You also should make sure that you have appropriate permissions on the control socket (use the ctl_perms option to make this sure) and of your pdnsd cache directory (pdnsd keeps its socket there). Please make sure the pdnsd cache directory is not writeable for untrusted users!

pdnsd-ctl accepts two command-line options starting with a dash.
-c may be used to specify the cache directory (and takes this as argument). The default for this setting is the pdnsd default cache directory (specified at compile time). The cache directory for pdnsd-ctl must be the same pdnsd uses!
-q can be used to make the output of pdnsd-ctl less verbose.

The following table lists the commands that pdnsd-ctl supports. The command must always be the first command-line option (not starting with a dash), the arguments to the command must follow in the given order.
In the following table, keywords are in a normal font, while placeholders are in italics.
Alternatives are specified like (alt1|alt2|alt3). Optional arguments are placed between square brackets [].

4 contrib/

5 Problems...

6 Hacking

6.1 Source files

Last revised: 27 February 2012 by Paul A. Rombouts