dan
/
tor-android
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
tor-android/jni/pdnsd/doc/txt/manual.txt

2018 lines
108 KiB
Plaintext
Raw Normal View History

add support for PDNSD DNS Daemon for VPN DNS resolution Tor's DNS port doesn't work well with the VPN mode, so we will use PDSND to resolve DNS over Tor using OpenDNS. This is a hack/solution that we learned from SocksDroid.
2016-01-04 06:38:36 +00:00
pdnsd Documentation
This is the "official" pdnsd documentation and reference written by Thomas
Moestl with revisions by Paul A. 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.9b. For older documentation, please
refer to the doc directory of the respective pdnsd package.
If you want a quicker introduction to pdnsd, you can try some of the HOWTOs
available on the web. 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/linux/library/
l-rpm1/.
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 < Has the same effect as --with-distribution=<distro> (
distro>" see below).
--define "run_as_user Has the same effect as --with-default-id=<user> (see
<user>" below).
For RPMs the default <user> is "pdnsd".
If the user defined by the previous option does not
--define "run_as_uid < exist when the RPM is installed, the pre-install script
uid>" 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 < Has the same effect as --with-cachedir=<dir> (see below
dir>" ).
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 pure sources (tar archives or git repositories)
0.3.1 Setting up the source code tree
Source code is available in the form of snapshots (tarballs) or a git
repository with the very latest development code and a (nearly) complete
history of all the revisions. Cloning a git repository is useful if you need a
recent fix or feature that is not yet contained in a main release or you want
to participate in pdnsd development. Otherwise you will probably find the
tarballs more convenient because they are much more compact.
0.3.1.1 Unpacking a tar archive
The pdsnsd snapshot releases come in the form of 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.1.2 Cloning a git repository
To clone a git repository you need to install, if not already installed, the
git version control system, which is available as a package in most modern
Linux distributions. Then run the command:
git clone git://gitorious.org/pdnsd/pdnsd.git pdnsd
In rare cases, if you are behind some kind of firewall, the special git
protocol can't be used and you will need to fall back to the http protocol. See
the gitorious.org website or git documentation for more information.
0.3.2 Configuring the source
Change into the pdnsd source directory and run configure. It takes the
following command line options (if you do not specify an option, defaults will
be used):
Specify the prefix directory. The pdnsd files are
installed in subdirectories of the prefix, the
--prefix=dir pdnsd and pdnsd-ctl executables are for example
installed in the sbin subdirectory of the prefix.
The default for this is /usr/local; you might want
to set this to /usr (using --prefix=/usr).
Specify the config directory. pdnsd expects its
pdnsd.conf file to reside there if the -c option is
--sysconfdir=dir 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= Specify target distribution (default=Generic;
distro others: RedHat, SuSE, Debian)
See below for the effect of these settings.
Change compilation target platform (default:
autodetect; others: Linux, BSD, Cygwin).
autodetect will attempt to detect whether you are
--with-target=platform 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).
Default directory for pdnsd cache (default=/var/
--with-cachedir=dir cache/pdnsd)
This setting can be changed via config file
settings when pdnsd has been built.
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
--with-hash-buckets=num 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 support
This option will work only on Linux and may cause
--enable-isdn problems with 2.0.x or old 2.2.x kernels. You will
need it for a proper if uptest under Linux for ISDN
ppp devices.
--disable-ipv4 Disable IPv4 networking support (default=enabled)
Enable IPv6 networking support.
--enable-ipv6 If your OS does support IPv6 properly, you should
be able to serve also IPv4 queries using this.
Normally, this is disabled and you won't need it.
--disable-ipv4-startup Disable IPv4 on pdnsd startup by default (default=
enabled)
Enable IPV6 on pdnsd startup by default (default=
IPv4). These options are only defaults, you can
--enable-ipv6-startup 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 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
--disable-tcp-queries 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.)
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
--with-query-method=qm 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 the TCP server. In this case pdnsd will not
--disable-tcp-server be able to respond to TCP queries from clients.
This may cause problems with very large answers.
Disable the UDP source address discovery.
You need this only if you have trouble with
--disable-src-addr-disc 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.
Since version 1.2.9 this option is obsolete and
ignored. It is now possible to configure for each
--disable-new-rrs RR type separately whether it is cacheable by pdnsd
by editing the file src/rr_types.in. The comments
in this file explain how to do this.
Enforce strict RFC 2181 compliance.
This will cause pdnsd to reject DNS answers with
--enable-strict-rfc2181 incorrect timestamp settings (multiple RRs of the
same type and for the same domain with different
TTLs). Normally not needed.
This option is obsolete. Since version 1.2, pdnsd
--enable-underscores places no restrictions on the types of characters
in domain names (there are still a few restrictions
for locally defined names, though).
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
--with-random-device= like; pdnsd will read random numbers from it
device 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).
Specify default user for pdnsd (default=nobody).
This is the user that will be entered for the
--with-default-id=user run_as option in the config file (see below) that
will be installed during make install. You can
change this any time in your config file.
Specify debugging level. 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
--with-debug=level 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 RCS IDs in executables (default=disabled).
--enable-rcsids For personal use, there is no need to do this. If
you build rpm's, it might have advantages.
Enable subsequent tcp queries. The DNS protocol
standard requires that servers must be capable of
answering multiple subsequent queries that are sent
over the same tcp connection, and that the server
may only close the connection by himself after a
certain timeout. This feature is rarely used, but
--enable-tcp-subseq may make denial-of-service attacks easier, as it
allows for an attacker to hold a connection open a
long time (although the attacker's IP is most
likely revealed then). For full standard
compliance, you should use this option. If you do
not use --enable-tcp-server, is option is not
honored.
Specify default tcp query timeout after which the
connection is closed if no full query has been
--with-tcp-qtimeout=secs 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.
Specify the default number of queries that can be
executed in parallel. You can also change this
--with-par-queries=num 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.
New in version 1.2.9b: Specify the maximum number
of IP addresses that can be used per nameserver
obtained from NS records (when resolving names
recursively). Just one IP address per nameserver is
sufficient in the vast majority of cases (and this
--with-max-nameserver-ips was the strategy used by pdnsd in previous
=num versions), but in rare cases this will cause
unnecessary resolve failures if the address chosen
for each nameserver happens to be unreachable while
the other addresses would lead to successful
resolution.
The default for this option is 3.
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
--with-thread-lib=lib 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:
* An rc script is copied in the appropriate localtion, which enables pdnsd to
start at machine boot time (see 0.4)
* Distribution-specific portions might be included in the generated
pdnsd.spec file (only important if you want to build rpm archives
yourself).
If you choose Generic, no rc script is 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,
Debian, Arch Linux and Slackware 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 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
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 ",;{}\". Since version 1.2.9 a backslash (\) inside a string
is interpreted as an escape character, so it is possible to include special
characters in strings (both quoted or unquoted) by preceding them with a
backslash. Some escape sequences are in interpreted as in the C programming
language, e.g. \t becomes a tab, \n becomes a new-line control char.
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 and listen on that
address. If the address of the interface changes while pdnsd is running, pdnsd
will not notice that. You will need to restart pdnsd in that case.
outgoing_ip=string;
or
outside_interface=string;
New in version 1.2.9: Set the IP address of the interface used by pdnsd for
outgoing queries. This can be useful when the host has several interfaces and
you want pdnsd to send outgoing queries via only one of them. For example, if
pdnsd is running on a host with one interface with IP address 192.168.1.1
connected to the local network, and another with IP address 123.xxx.yyy.zzz
connected to the internet, you may specify server_ip=192.168.1.1 and
outgoing_ip=123.xxx.yyy.zzz to enforce that pdnsd only responds to queries
received from the local network, and only sends outgoing queries via the
interface connected to the internet.
The default setting for this option is any, which means that the kernel is free
to decide which interface to use. Like with the server_ip option, you may also
give the name of an interface here, instead of an IP address.
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=timespec;
This option sets the maximum time a record is held in cache. 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=timespec;
This option sets the minimum time a record is held in cache. 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=timespec;
This option sets the time that negatively 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 negatively, and additionally when record types
are cached negatively 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|default);
This sets the RR set policy for negative caching; this tells pdnsd under which
circumstances it should cache a record type negatively for a certain domain.
off will turn the negative caching 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.
New in version 1.2.8: The default setting will add a negatively cached record
if either the answer was authoritive or the answer indicated the name server
had "recursion available" while the query explicitly requested such recursion.
The preset is "default" (used to be auth).
neg_domain_pol=(on|off|auth);
This is analogue to neg_rrs_pol for whole domain negative caching. It should be
safe to set this on, because I have not seen a caching server that will falsely
claim that a domain does not exist.
The default is 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.
ignore_cd=(on|off);
New in version 1.2.8: This option lets you specify that the CD bit of a DNS
query will be ignored. Otherwise pdnsd will reply FORMERR to clients that set
this bit in a query. It is safe to enable this option, as the CD bit refers to
'Checking Disabled' which means that the client will accept non-authenticated
data.
This option is on by default. Turn it off if you want the old behaviour (before
version 1.2.8).
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.
Added by Paul Rombouts: Note that pdnsd-ctl allows run-time configuration of
pdnsd, even the IP addesses of the name servers can be changed. If you're not
using pdnsd-ctl and you want maximum security, you should not enable this
option. It is disabled by default.
daemon=(on|off);
This has the same effect as the -d command line option: the daemon mode is
enabled when on is specified.
Default is off.
tcp_server=(on|off);
tcp_server=on has the same effect as the -t or --tcp command-line option: it
enables TCP serving. Similarly, tcp_server=off is like the --notcp command-line
option.
Default is on.
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|udp_tcp);
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, tcp_udp to the tu and udp_tcp to the ut argument of the command line
option.
If you use query_method=tcp_udp, it is recommended that you also set the global
timeout option to at least twice the longest server timeout.
run_ipv4=(on|off);
This has the same effect as the -4 or -6 command line option: if on is
specified, IPv4 support is enabled, and IPv6 support is disabled (if
available). If off is specified, IPv4 will be disabled and IPv6 will be
enabled. For this option to be meaningful, pdnsd needs to be compiled with
support for the protocol you choose. If pdnsd was compiled with both IPv4 and
IPv6 support, and you want to include IPv6 addresses in the configuration file,
you will probably need to specify run_ipv4=off first to ensure that the IPv6
addresses are parsed correctly.
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 is 40.
procq_limit=number;
When the query thread limit proc_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. A maximum of proc_limit+procq_limit query
threads will exist at any one time (plus 3 to 6 threads that will always be
present depending on your configuration).
The default for this option is 60.
tcp_qtimeout=timespec;
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 used to set the maximum number of remote servers that would be
queried simultaneously, for every query that pdnsd receives.
Since version 1.1.11, the meaning of this option has changed slightly. It is
now the increment with which the number of parallel queries is increased when
the previous set of servers has timed out. For example, if we have a list
server1, server2, server3, etc. of available servers and par_queries=2, then
pdnsd will first send queries to server1 and server2, and listen for responses
from these servers.
If these servers do not send a reply within their timeout period, pdnsd will
send additional queries to server3 and server4, and listen for responses from
server1, server2, server3 and server4, and so on until a useful reply is
received or the list is exhausted.
In the worst case there will be pending queries to all the servers in the list
of available servers. We may be using more system resources this way (but only
if the first servers in the list are slow or unresponsive), but the advantage
is that we have a greater chance of catching a reply. After all, if we wait
longer anyway, why not for more servers.
See also the explanation of the global timeout option below.
1 or 2 are good values for this option. The default is set at compile time
using the --with-par-queries option to configure.
timeout=timespec;
This is the global timeout parameter for dns queries. This specifies the
minimum period of time pdnsd will wait after sending the first query to a
remote server before giving up without having received a reply. The timeout
options in the configuration file are now only minimum timeout intervals.
Setting the global timeout option makes it possible to specify quite short
timeout intervals in the server sections (see below). This will have the effect
that pdnsd will start querying additional servers fairly quickly if the first
servers are slow to respond (but will still continue to listen for responses
from the first ones). This may allow pdnsd to get an answer more quickly in
certain situations.
If you use query_method=tcp_udp it is recommended that you make the global
timeout at least twice as large as the largest server timeout, otherwise pdnsd
may not have time to try a UDP query if a TCP connection times out.
Default value is 0.
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|none);
If a number is given, this 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 larger range is highly recommended for security reasons, and
also because other applications may allocate ports in that range. If possible,
this range should be kept out of the space that other applications usually use.
The default for this option is 1024. Together with the default value of
query_port_end, this makes it the hardest for an attacker to guess the source
port used by the pdnsd resolver. If you specify none here, pdnsd will let the
kernel choose the source port, but this may leave pdnsd more vulnerable to an
attack.
query_port_end=number;
Used if query_port_start is not none. 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.
delegation_only=string;
Added by Paul Rombouts: This option specifies a "delegation-only" zone. This
means that if pdnsd receives a query for a name that is in a subdomain of a
"delegation-only" zone but the remote name server returns an answer with an
authority section lacking any NS RRs for subdomains of that zone, pdnsd will
answer NXDOMAIN (unknown domain). This feature can be used for undoing the
undesired effects of DNS "wildcards". Several "delegation-only" zones may be
specified together. If you specify root servers in a server section it is
important that you set root_server=on in such a section.
Example:
delegation_only="com","net";
This feature is off by default. It is recommended that you only use this
feature if you actually need it, because there is a risk that some legitimate
names will be blocked, especially if the remote name servers queried by pdnsd
return answers with empty authority sections.
ipv4_6_prefix=string;
This option has the same effect as the -i command-line option. When pdnsd runs
in IPv6 mode, this option specifies the prefix pdnsd uses to convert IPv4
addresses in the configuration file (or addresses specified with pdnsd-ctl) to
IPv6-mapped addresses. The string must be a valid IPv6 address. Only the first
96 bits are used. Note that this only effects the parsing of IPv4 addresses
listed after this option.
The default is "::ffff.0.0.0.0".
use_nss=(on|off);
If this option is turned on, pdnsd will call initgroups() to set up the group
access list, whenever pdnsd changes its user and group id (see run_as option).
There is a possible snag, though, if initgroups() uses NSS (Name Service
Switch) and NSS in turn uses DNS. In such a case you may experience lengthy
timeouts and stalls. By setting use_nss=off, you can disable the initgroups()
call (only possible in versions 1.2.5 and later).
This option was contributed by Jan-Marek Glogowski.
On by default.
udpbufsize=number;
New in version 1.2.9: This option sets the upper limit on the size of UDP DNS
messages. The default is 1024.
See also the edns_query server option below.
2.1.2 server Section
Each server section specifies a set of name servers that pdnsd should try to
get resource records or authoritative name server information from. The servers
are 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
servers of your internet provider or even a list of root servers in one or more
server sections.
The supported options in this section are:
label=string;
Specify a label for the server section. This can be used to refer to this
section when using pdnsd-ctl, the pdnsd control utility.
You can give several server sections the same label, but if you want to change
the addresses of a server section (see ip option below) during run-time with
"pdnsd-ctl server label up dns1,dns2,...", the label must be unique.
ip=string;
Give the IP (the address, not the host name) of the server.
Multiple IP addresses can be given per server section. This can be done by
entering multiple lines of the form ip=string; or a single line like this:
ip=string,string,string;
IP addresses do not have to be specified in the configuration file. A server
section without IP addresses will remain inactive until it is assigned one or
more addresses with pdnsd-ctl, the pdnsd control utility.
If pdnsd has been compiled with both IPv4 and IPv6 support, any IPv6 addresses
you specify here will be skipped with a warning message, unless pdnsd is
running in IPv6 mode. Thus, unless pdnsd was compiled to startup in IPv6 mode
by default, you need to use the command-line option -6 or set run_ipv4=off
first (see global section) in order to ensure that IPv6 addresses are 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.
file=string;
New in version 1.2: This option allows you to give the name of a
resolv.conf-style file. Of the lines beginning with the nameserver keyword, the
second field will be parsed as an IP address, as if it were specified with the
ip= option. The remaining lines will be ignored. If the contents of the file
changes while pdnsd is running, you can make pdnsd aware of the changes through
the use of pdnsd-ctl, the pdnsd control utility. This is usually most
conveniently done by placing the command "pdnsd-ctl config" in a script that is
automatically run whenever the DNS configuration changes.
For example, suppose you have a ppp client that writes the DNS configuration
for your ISP to the file /etc/ppp/resolv.conf and runs the script /etc/ppp/
ip-up when a new connection is established. One way of ensuring that pdnsd is
automatically reconfigured is to add a server section in the config file with
file=/etc/ppp/resolv.conf and to add the command "pdnsd-ctl config" to /etc/ppp
/ip-up.
port=number;
Give the port the remote name server listens on. Default is 53 (the official
dns port)
uptest=(ping|none|if|dev|diald|exec|query);
Determine the method to check whether the server is available. Currently
defined methods are:
* ping: Send an ICMP_ECHO request to the server. If it doesn't respond within
the timeout, it is regarded to be unavailable until the next probe.
* none: The availability status is not changed, only the time stamp is
updated.
* if: Check whether the interface (specified in the interface= option) is
existent, up and running. This currently works for all "ordinary" network
interfaces, interfaces that disappear when down (e.g. ppp?), and
additionally for Linux isdn interfaces (as of kernel 2.2). Note that you
need a /dev/isdninfo device file (major#45, minor#255), or the isdn uptest
will always fail.
* dev and diald: Perform an if uptest, and, if that was succesful,
additionally check whether a program is running that has locked a given
(modem-) device. The needed parameters are an interface (specified as for
the if uptest, e.g. "ppp0") and a device relative to /dev (e.g. "modem" for
/dev/modem specified using the device= option. pdnsd will then look for a
pid file for the given interface in /var/lock (e.g. /var/run/ppp0.pid) and
for a lockfile for the given device (e.g. /var/lock/LCK..modem), and then
test whether the locking process is the process that created the pid file
and this process is still alive. If this is the case, the normal if uptest
is executed for the given interface.
The dev option is for pppd dial-on-demand, diald is the same for diald
users.
* exec: Executes a given command in the /bin/sh shell (as /bin/sh -c
<command>) and evaluates the result (the return code of the last command)
in the shell's way of handling return codes, i.e. 0 indicates success, all
other indicate failure. The shell's process name will be uptest_sh. The
command is given with the uptest_cmd option (see below). For secuity
issues, also see that entry.
* query: New in version 1.2: This works like the ping test, except it sends
an (empty) DNS query to the remote server. If the server sends a
well-formed response back within the timeout period (except SERVFAIL), it
will be regarded as available. This test is useful if a remote server does
not respond to ICMP_ECHO requests at all, which unfortunately is quite
common these days. It can also happen that a remote server is online but
ignores empty DNS queries. Then you will need the set the query_test_name
option (see below). In many cases this test will be a more reliable
indicator of availability than the ones mentioned before.
The default value is none.
NOTE: If you use on-demand dialing, use none, if, dev, diald or exec, since
ping or query will send packets in the specified interval and the interface
will thus frequently dial!
ping_timeout=number;
Sets the timeout for the ping test in tenths of seconds (this unit is used for
legacy reasons; actually the current implementation is only accurate to a
second).
The default is 600 (one minute).
ping_ip=string;
The IP address for the ping test. The default is the IP of the name server.
query_test_name=string;
New in version 1.2.9: Sets the name to be queried when using uptest=query
availability test. If the string is the unquoted constant none, an empty query
is used (this the default), otherwise a query of type A will be sent for the
domain name specified here. It is not necessary for the domain name to exist or
have a record of type A in order for the uptest to succeed.
If the the remote server ignores empty queries, you will probably want to set
query_test_name="." (the root domain).
uptest_cmd=string,string;
or
uptest_cmd=string;
Sets the command for the uptest=exec function to the first string. If the
second string is given, it specifies a user with whose user id and primary
group id the command is executed.
This is especially useful if you are executing the server as root, but do not
want the uptest to be performed with root privileges. In fact, you should never
execute the uptest as root if you can help it.
If the server is running setuid or setgid, the privileges thus gained are
attempted to be dropped even before changing identity to the specified user to
prevent setuid/gid security holes (otherwise, any user might execute commands
as root if you setuid the executable).
Note that this is not always possible, and that pdnsd should never be installed
as setuid or setgid. The command is executed using /bin/sh, so you should be
able to use shell builtin commands.
interval=(timespec|onquery|ontimeout);
Sets the interval for the server up-test. The default is 900 seconds; however,
a test is forced when a query times out and the timestamp is reset then.
If you specify onquery instead of a timeout, the interface will be tested
before every query. This is to prevent automatically dialing interfaces (diald/
pppd or ippp) to dial on dns queries. It is intended to be used in connection
with an interface-testing uptest ;-)
Note that using uptest=exec, you might run into performance problems on slow
machines when you use that option. DON'T use onquery with uptest=ping or uptest
=query, as it may cause delays if the server does not answer (btw, it doesn't
make sense anyway). Note also that using onquery is no guarantee that the
interface will not be used. When another (reachable) dns server tells pdnsd to
query a third dns server for data, pdnsd will do that and has no means of
checking whether this will dial up the interface or not. This however should be
a rare situation.
New in version 1.2.3: A third possibility is to specify interval=ontimeout. In
this case the server is not tested at startup/reconfiguration, nor at regular
intervals, but only after a DNS query to a server times out. Certain types of
network problems such as a refused connection will also cause the server to be
considered unavailable. However, once a server is declared dead it is never
considered again unless it is revived using a pdnsd-ctl config or server
command. The idea behind this option is to minimize uptests by assuming all
servers are available until there is reason to believe otherwise.
interface=string;
The network interface (or network device, e.g. "eth0") for the uptest=if
option. Must be specified if uptest=if is given.
device=string;
The (modem-) device that is used for the dev uptest. If you use this for a
dial-on-demand ppp uptest (together with uptest=dev), you need to enter the
device you are using for your pppd here, e.g. modem for /dev/modem.
Must be specified if uptest=dev is given.
timeout=timespec;
Set the timeout for the dns query. The default is 120 seconds. You probably
want to set this lower.
Timeouts specified in the configuration file are only treated as the minimum
period of time to wait for a reply. A queries to a remote server are not
canceled until a useful reply has been received, or all the other queries have
timed out or failed.
If you have also set the global timeout option, you may consider setting a
fairly small value here. See the explanation of the timeout option in the
global section for what that means.
purge_cache=(on|off);
In every fetched dns record, there is a cache timeout given, which specifies
how long the fetched data may be cached until it needs to be reloaded. If
purge_cache is set to off, the stale records are not purged (unless the cache
size would be exceeded, in this case the oldest records are purged). Instead,
they are still served if they cannot succesfully be updated (e.g. because all
servers are down).
Default is off.
caching=(on|off);
Specifies if caching shall be performed for this server at all. Default is on.
lean_query=(on|off);
Specifies whether to use the "lean" query mode. In this mode, only the
information actually queried from pdnsd is resolved and cached. This has the
advantage that usually less cache space is used and the query is usually
faster. In 90% of the cases, only address (A) records are needed anyway. If
switched off, pdnsd will always cache all data about a host it can find and
will specifically ask for all available records (well, at least it is a good
approximation for what it really does ;-) This will of course increase the
answer packet sizes.
Some buggy name servers may not deliver CNAME records when not asked for all
records. I do not know if such servers are around, but if you have trouble
resolving certain host names, try turning this option off.
A last note: If you use multiple pdnsd's that access each other, turning this
option on is probably a big win.
This on by default.
edns_query=(on|off);
New in version 1.2.9: Specifies whether to use EDNS (Extension mechanisms for
DNS) for outgoing queries. Currently this is only useful for allowing UDP
message sizes larger than 512 bytes. Note that setting this option on can give
problems in combination with some legacy systems or software, including,
embarrassingly enough, previous versions of pdnsd.
The default is off, but if your network can handle UDP payloads significantly
larger than 512 bytes, the recommended value is on.
Note that this option only effects outgoing queries. If pdnsd receives a query
using EDNS, it will reply using EDNS regardless of the value of this option.
See also the udpbufsize option above.
scheme=string;
You can specify a pcmcia-cs scheme that is used in addition to the uptests. If
you specify a scheme here, the server this section is for will only be queries
if the given scheme is active. Shell wildcards (* and ?) are allowed in the
string under their special meanings. You need to use the scheme_file option on
the global section to make this option work.
preset=(on|off);
This allows you to specify the initial state of a server before any uptest is
performed. on specifies that the server is regarded available. The default is
on. This is especially useful when you set uptest=none; and want to change the
status of a server only via pdnsd-ctl.
proxy_only=(on|off);
When this option is set to on, answers given by the servers are always
accepted, and no other servers (as, for example, specified in the NS records of
the query domain) are queried. If you do not turn this option on, pdnsd will do
such queries in some cases (in particular when processing ANY queries).
This option is useful when you do not want pdnsd to make connections to outside
servers for some reasons (e.g. when a firewall is blocking such queries).
I recommend that you turn on lean_query when using this option.
Default is off.
root_server=(on|off|discover);
Set this option to on if the servers specified in a section are root servers. A
root server will typically only give the name servers for the top-level domain
in its reply. Setting root_server=on will cause pdnsd to try to use cached
information about top-level domains to reduce to number of queries to root
servers, making the resolving of new names more efficient. You can get a list
of available root servers by running the command "dig . ns".
This option is also necessary if you use the delegation_only option.
New in version 1.2.8: This option may also be set to "discover". This will
cause pdnsd to query the servers provided with the ip= option to obtain the
full list of root servers. The root-server addresses will replace the addresses
specified with the ip= option. This will only be done once on startup, or after
a "pdnsd-ctl config" command. In this case the name servers specified with the
ip= option don't have to be root servers, they just have to know the names and
addresses of the root servers. After root-server discovery pdnsd will behave
just as if root_server=on had been specified.
Default is off.
randomize_servers=(on|off);
New in version 1.2.6: Set this option to on to give each name server in this
section an equal chance of being queried. If this option is off, the name
servers are always queried starting with the first one specified. Even with
this option on, the query order is not truly random. Only the first server is
selected randomly; the following ones are queried in consecutive order,
wrapping around to the beginning of the list when the end is reached. Note that
this option only effects the order within a section. The servers in the first
(active) section are always queried before those in the second one, etc.
The default is off, but if you are resolving from root servers setting this
option on is highly recommended. If root_server=on this option also effects the
query order of the name servers for the top-level domains.
reject=string;
New in version 1.2.6: This option can be used to make pdnsd reject replies that
contain certain IP addresses. You can specify a single IP address, which will
be matched exactly, or a range of addresses using an address/mask pair. The
mask can be specified as a simple integer, indicating the number of initial 1
bits in the mask, or in the usual IP address notation. IP addresses may be
either IPv4 or IPv6 (provided there is sufficient support in the C libraries
and support for AAAA records was not disabled). When addresses in the reject
list are compared with those in a reply, only the bits corresponding to those
set in the netmask are significant, the rest are ignored.
Multiple addresses or address/mask pairs may be specified; this can be done by
entering multiple lines of the form reject=string; or a single line like this:
reject=string,string,string;
How pdnsd reacts when an address in the reply matches one in the reject list,
depends on the reject_policy option, see below.
reject_policy=(fail|negate);
New in version 1.2.6: This option determines what pdnsd does when an address in
the reply from a name server matches the reject list (see above). If this
option is set to fail, pdnsd will try another server, or, if there no more
servers to try, return the answer SERVFAIL. If this option is set to negate,
pdnsd will immediately return the answer NXDOMAIN (unknown domain) without
querying additional servers. The fail setting is useful if you don't always
trust the servers in this section, but do trust the servers in the following
section. The negate setting can be used to completely censor certain IP
addresses. In this case you should put the same reject list in every server
section, and also set the reject_recursively option (see below) to true.
The default is fail.
reject_recursively=(on|off);
New in version 1.2.6: Normally pdnsd checks for addresses in the reject list
(see above) only when the reply comes directly from a name server listed in the
configuration file. With this option set to on, pdnsd will also do this check
for name servers that where obtained from NS records in the authority section
of a previous reply (which was incomplete and non-authoritative).
Default is off.
policy=(included|excluded|simple_only|fqdn_only);
pdnsd supports inclusion/exclusion lists for server sections: with include= and
exclude= (see below) you can specify domain names for which this server will be
used or will not be used. The first match counts (i.e., the first include or
exclude rule in a server section that matches a domain name is applied, and the
search for other rules is terminated). If no rule matched a given domain name,
the policy= option determines whether this server is used for the lookup for
that domain name; when included is given, the server will be asked, and when
excluded is given, it will not. If simple_only is given the server will be used
if the name to lookup is a simple (single-label) domain name, on the other hand
if fqdn_only is given the server will be used only for names consisting of two
or more labels (i.e. the name has at least one dot in-between).
If no server is available for a queried domain, pdnsd will return an error
message to the client that usually will stop the client's attempts to resolve a
specific domain from this server (the libc resolver will e.g. return an error
to the application that tried to resolve the domain if no other servers are
available in the resolv.conf). This may be of use sometimes.
Note: the simple_only and fqdn_only constants were added by Paul Rombouts. They
are useful for controlling which name servers (if any) will be used by pdnsd
for resolving simple (single-label) host names. fqdn_only used to stand for
"fully qualified domain name only", but this is actually a misnomer. The names
in queries received by pdnsd are always considered to be fully qualified. If
you do not exactly understand what the options simple_only and fqdn_only are
good for, you are probably better off not using them.
The default for this option is included.
include=string;
This option adds an entry to the exclusion/inclusion list. If a domain matches
the name given as string, the server is queried if this was the first matching
rule (see also the entry for policy).
If the given name starts with a dot, the whole subdomain of the given name
including the one of that name is matched, e.g. ".foo.bar." will match the
domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case,
of course) will be matched (hint: if you want to include all subdomains, but
not the domain of the given name itself, place an exact-match exclude rule
before the include rule, e.g: exclude="foo.bar."; include=".foo.bar.";
Previous versions of pdnsd required that names given with this and the next
option ended in a dot, but since version 1.1.8b1-par8, pdnsd automatically adds
a dot at the end if it is missing.
pdnsd now also accepts a more compact notation for adding several "include"
entries in one line, e.g.:
include=".foo",".bar",".my.dom";
exclude=string;
This option adds an entry to the exclusion/inclusion list. If a domain matches
the name given as string, the server is not queried if this was the first
matching rule (see also the entry for policy).
If the given name starts with a dot, the whole subdomain of the given name
including the one of that name is matched, e.g. ".foo.bar." will match the
domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case,
of course) will be matched (hint: if you want to exclude all subdomains, but
not the domain of the given name itself, place an exact-match include rule
before the exclude rule, e.g: include="foo.bar."; exclude=".foo.bar.";
pdnsd now also accepts a more compact notation for adding several "exclude"
entries in one line, e.g.:
exclude=".foo",".bar",".my.dom";
2.1.3 rr Section
Every rr section specifies a dns resource record that is stored locally. It
allows you to specify own dns records that are served by pdnsd in a limited
way. Only A, PTR, CNAME, MX, NS and SOA records are implemented.
This option is intended to allow you to define RRs for 1.0.0.127.in-addr.arpa.
and localhost. (and perhaps even one or two hosts) without having to start an
extra named if your cached name servers do not serve those records. It is NOT
intended and not capable to work as a full-featured name server.
name=string;
Specifies the name of the resource records, i.e. the domain name of the
resource the record describes. This option must be specified before any a, ptr,
cname, mx, ns or soa records. Names are interpreted as absolute domain names
(i.e. pdnsd assumes they end in the root domain). For this and all following
arguments that take domain names, you need to specify domain names in dotted
notation (example venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the
configuration file ended in a dot, but since version 1.1.8b1-par8, pdnsd
automatically assumes a dot at the end if it is missing.
New in version 1.2: It is also possible to specify a name starting with the
label *. Such a name is called a wildcard. The * in a wildcard can match one or
more labels in a queried name, but only whole labels. Any other * characters in
a wildcard, apart from the leading one, will only match a literal *.
For example, *.mydomain will match a.mydomain or www.a.mydomain, but not
mydomain. *.a*.mydomain will match www.a*.mydomain, but not www.ab.mydomain.
*a.mydomain will only match itself.
Before you can specify an rr section with name=*.mydomain you must define some
records for mydomain, typically NS and/or SOA records. Example:
rr {
name = mydomain;
ns = localhost;
soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
}
rr {
name = *.mydomain;
a = 192.168.1.10;
}
In this example, www.mydomain and ftp.mydomain will resolve to the numeric
address 192.168.1.10 (unless you add rr sections explicitly specifying
different addresses for www.mydomain or ftp.mydomain). If you want mydomain
also to resolve to a numeric address, add an A record to the first rr section.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local records for this rr
section. This means that pdnsd flags the domain record so that records of this
domain that are not present in the cache are treated as non-existent, i.e. no
other servers are queried for that record type, and an response containing none
of those records is returned. This is most time what people want: if you add an
A record for a host, and it has no AAAA record (thus no IPv6 address), you
normally don't want other name servers to be queried for it.
This is on by default.
Please note that this only has an effect if it precedes the name option!
reverse=(on|off);
New in version 1.2: If you want a locally defined name to resolve to a numeric
address and vice versa, you can achieve this by setting reverse=on before
defining the A record (see below). The alternative is to define a separate PTR
record, but you will probably find this option much more convenient.
The default is off.
a=string;
Defines an A (host address) record. The argument is an IPv4 address in dotted
notation. pdnsd will serve this address for the host name given in the name
option.
Provided there is sufficient support in the C libraries and support for AAAA
records was not disabled, the argument string may also be an IPv6 address, in
which case an AAAA record will be defined.
This option be may used multiple times within an rr section, causing multiple
addresses to be defined for the name. However, if you put the different
addresses in different rr sections for the same name, the definition in the
last rr section will cancel the definitions in the previous ones.
ptr=string;
Defines a PTR (domain name pointer) record. The argument is a host name in
dotted notation (see name). The ptr record is for resolving adresses into
names. For example, if you want the adress 127.0.0.1 to resolve into localhost,
and localhost into 127.0.0.1, you need something like the following sections:
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;
}
The second section is for reverse resolving and uses the ptr option. Note that
you can get the same effect by specifying only the first rr section with
reverse=on.
There is something special about the name in the second section: when a
resolver wants to get a host name from an internet address, it composes an
address that is built of the IP address in reverse byte order (1.0.0.127
instead of 127.0.0.1) where each byte of the adress written as number
constitutes a sub-domain under the domain in-addr.arpa.
So, if you want to compose an adress for reverse resolving, take your ip in
dotted notation (e.g. 1.2.3.4), reverse the byte order (4.3.2.1) and append
in-addr.arpa. (4.3.2.1.in-addr.arpa.) Then, define an rr section giving this
address as name and the domain name corresponding to that ip in the ptr option.
cname=string;
Defines a CNAME (canonical name) record. The argument should be a
fully-qualified host name in dotted notation (see name). A CNAME is the DNS
equivalent of an alias or symbolic link.
A useful application for CNAMEs is giving short, easy to remember nicknames to
hosts with complicated names. For example, you might want the name "news" to
refer to your ISP's news server "nntp2.myisp.com". Instead of adding an A
record for "news" with the same address as "nntp2.myisp.com", you could put in
a CNAME pointing to "nntp2.myisp.com", so that if the IP address of the news
server changes, there is no need to update the record for "news".
To implement this with pdnsd, you could add the following section to your
configuration file:
rr {
name = news;
cname = nntp2.myisp.com;
owner = localhost;
}
mx=string,number;
Defines an MX (mail exchange) record. The string is the host name of the mail
server in dotted notation (see name). The number specifies the preference
level.
When you send mail to someone, your mail typically goes from your E-mail client
to an SMTP server. The SMTP server then checks for the MX record of the domain
in the E-mail address. For example, with joe@example.com, it would look for the
MX record for example.com and find that the name of mail server for that domain
is, say, mail.example.com. The SMTP server then gets the A record for
mail.example.com, and connects to the mail server.
If there are multiple MX records, the SMTP server will pick one based on the
preference level (starting with the lowest preference number, working its way
up).
Don't define MX records with pdnsd unless you know what you're doing.
owner=string;
or
ns=string;
Defines an NS (name server) record. Specifies the name of the host which should
be authoritative for the records you defined in the rr section. This is
typically the host pdnsd runs on.
Note: In previous versions of pdnsd this option had to be specified before any
a, ptr, cname, mx or soa entries. In version 1.2, the restrictions on this
option are same as the options just mentioned, and it must listed after the
name= option. This can be a pain if you want to use an old config file which
specifies owner= before name= (sorry about that). Apart from greater
consistency, the advantage is that you can now specify as many NS records as
you like (including zero).
soa=string,string,number,timespec,timespec,timespec,timespec;
This defines a soa (start of authority) record. The first string is the domain
name of the server and should be equal to the name you specified as owner.
The second string specifies the email address of the maintainer of the name
server. It is also specified as a domain name, so you will have to replace the
@ sign in the name with a dot (.) to get the name you have to specify here. The
next parameter (the first number) is the serial number of the record. You
should increment this number if you change the record.
The 4th parameter is the refresh timeout. It specifies after what amount of
time a caching server should attempt to refresh the cached record.
The 5th parameter specifies a time after which a caching server should attempt
to refresh the record after a refresh failure.
The 6th parameter defines the timeout after which a cached record expires if it
has not been refreshed.
The 7th parameter is the ttl that is specified in every rr and should be the
same as given with the ttl option (if you do not specify a ttl, use the default
86400).
txt=string,...,string;
New in version 1.2.9: Defines an TXT record. You can specify one or more
strings here.
2.1.4 neg Section
Every neg section specifies a dns resource record or a dns domain that should
be cached negatively locally. Queries for negatively cached records are always
answered immediatley with an error or an empty answer without querying other
hosts as long as the record is valid. The records defined with neg sections
remain valid until they are explicitely invalidated or deleted by the user
using pdnsd-ctl.
This is useful if a certain application asks periodically for nonexisting hosts
or RR types and you do not want a query to go out every time the cached record
has timed out. Example: Netscape Communicator will ask for the servers news and
mail on startup if unconfigured. If you do not have a dns search list for your
network, you can inhibit outgoing queries for these by specifying
neg {
name = news;
types = domain;
}
neg {
name = mail;
types = domain;
}
in your config file. If you have a search list, you have to repeat that for any
entry in your search list in addition to the entries given above!
In versions 1.1.11 and later, if you negate whole domains this way, all
subdomains will be negated as well. Thus if you specify
neg {name=example.com; types=domain;} in the config file, this will also negate
www.example.com, xxx.adserver.example.com, etc.
name=string;
Specifies the name of the domain for which negative cache entries are created.
This option must be specified before the types option. Names are interpreted as
absolute domain names (i.e. pdnsd assumes they end in the root domain). You
need to specify domain names in dotted notation (example venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the
configuration file ended in a dot, but since version 1.1.8b1-par8, pdnsd
automatically assumes a dot at the end if it is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
types=(domain|rr_type[,rr_type[,rr_type[,...]]]);
Specifies what is to be cached negatively: domain will cache the whole domain
negatively; alternatively, you can specify a comma-separated list of RR types
which are to be cached negatively. You may specify multiple types options, but
domain and the RR types are mutually exclusive.
The RR types are specified using their official names from the RFC's in
capitals, e.g. A, CNAME, NS, PTR, MX, AAAA, ...
The command pdnsd-ctl list-rrtypes will give you a complete list of those
types. pdnsd-ctl is built along with pdnsd and will be installed in the same
directory as the pdnsd binary during make install.
2.1.5 source Section
Every source section allows you to let pdnsd read the records from a file in an
/etc/hosts-like format. pdnsd will generate records to resolve the entries
address from its host name and vice versa for every entry in the file. This is
normally easier than defining an rr for every of your addresses, since
localhost and your other FQDNs are normally given in /etc/hosts.
The accepted format is as follows: The #-sign initiates a comment, the rest of
the line from the first occurence of this character on is ignored. Empty lines
are tolerated.
The first entry on a line (predeceded by an arbitrary number of tabs and
spaces) is the IP in dotted notation, the second entry on one line (separated
by the first by an arbitrary number of tabs and spaces) is the FQDN (fully
qualified domain name) for that ip. The rest of the line is ignored by default
(in the original /etc/hosts, it may contain information not needed by pdnsd).
owner=string;
Specifies the name of the host pdnsd runs on and that are specified in dns
answers (specifically, nameserver records). Must be specified before any file
entries.
Names are interpreted as absolute domain names (i.e. pdnsd assumes they end in
the root domain). You need to specify domain names in dotted notation (example
venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the
configuration file ended in a dot, but since version 1.1.8b1-par8, pdnsd
automatically assumes a dot at the end if it is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
file=string;
The string specifies a file name. For every file entry in a source section,
pdnsd will try to load the given file as described above. Failure is indicated
only when the file cannot be opened, malformed entries will be ignored.
serve_aliases=(on|off);
If this is turned on pdnsd will serve the aliases given in a hosts-style file.
These are the third entry in a line of a hosts-style file, which usually give a
"short name" for the host. This may be used to support broken clients without a
proper domain-search option. If no aliases are given in a line of the file,
pdnsd behaves as without this option for this line.
This feature was suggested by Bert Frederiks.
It is off by default.
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local records with the
data from the hosts file. Please see the description of the option of the same
name in the rr section for a closer description of what this means. Please note
that this only has an effect for files sourced with file options subsequent to
this option.
This is on by default.
2.1.6 include Section
A configuration file may include other configuration files. However, only the
top-level configuration file may contain global and server sections, thus
include files are effectively limited to sections that add local definitions to
the cache.
Include sections currently only have one type of option, which may be given
multiple times within a single section.
file=string;
The string specifies a file name. For every file option in an include section,
pdnsd will parse the given file as described above. The file may contain
include sections itself, but as a precaution pdnsd checks that a certain
maximum depth is not exceeded to guard against the possibility of infinite
recursion.
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 [].
Command Arguments Description
help Print a command summary.
version Print version and license info.
status Print a description of pdnsd's cache status, thread status
and configuration. Also shows which remote name servers
are assumed to be available.
server (index|label) (up| Set the status of the server with the given index or label
down|retest) [dns1[, (where the given label matches the one given with the
dns2[,...]]] label option in the respective server section in the
config file) to up or down, or force a retest. The index
is assigned in the order of definition in pdnsd.conf
starting with 0. Use the status command to view the
indices and labels. You can specify all instead of an
index or label to perform the action for all servers
registered with pdnsd. Example:
pdnsd-ctl server 0 retest
An optional third argument consisting of a list of IP
addresses (separated by commas or white-space characters)
can be given. This list will replace the previous list of
addresses of name servers used by pdnsd in the specified
section of the config file. For example in the /etc/ppp/
ip-up script called by pppd you could place the following
line:
pdnsd-ctl server isplabel up $DNS1,$DNS2
If white space is used to separate addresses the list will
have to be quoted. Spurious commas and white-space
characters are ignored. The last argument may also be an
empty string, in which case the existing IP addresses are
removed and the corresponding server section becomes
inactive.
record name (delete| Delete or invalidate the records of the given domain name
invalidate) if it is in the cache. Invalidation means that the records
are marked as timed out, and will be reloaded if possible
(if purge_cache is set to on, they will be deleted in any
case).
For local records (i.e., records that were given in the
config file using a rr section, records read from a
hosts-style file and records added using pdnsd-ctl),
invalidation has no effect. Deletion will work, though.
Example:
pdnsd-ctl record localhost. delete
source fn owner [ttl] [(on Load a hosts-style file. Works like using the pdnsd source
|off)] [noauth] configuration section. owner and ttl are used as in the
source section. ttl has a default of 900 (it does not need
to be specified). The next to last argument corresponds to
the serve_aliases option, and is off by default (i.e. if
it is not specified). noauth is used to make the domains
non-authoritative - please see the description of the
authrec config file options for a description of what that
means. fn is the filename. The file must be readable by
pdnsd! Example:
pdnsd-ctl source /etc/hosts localhost. 900 off
add a addr name [ttl]
[noauth]
Add a record of the given type to the pdnsd cache,
replacing existing records for the same name and type. The
add aaaa addr name [ttl 2nd argument corresponds to the value of the option in the
] [noauth] rr section that is named like the first argument: a is a
record for hostname-to-address mapping, aaaa is the same
thing for IPv6 addresses, and ptr is for
add ptr host name [ttl] address-to-hostname mapping. See the documentation for the
[noauth] rr section for more details. In case of A and AAAA
records, the addr argument may be a list of IP addresses,
separated by commas or white space, causing multiple
add cname host name [ addresses to be defined for the same name. The ttl is
ttl] [noauth] optional, the default is 900 seconds. noauth is used to
make the domains non-authoritative - please see the
description of the authrec config file options for a
add mx host name pref description of what that means. If you want no other
[ttl] [noauth] record than the newly added in the cache, do
pdnsd-ctl record name delete before adding records. This
is also better when overwriting local records. Example:
add ns host name [ttl] pdnsd-ctl add a 127.0.0.1 localhost. 900
[noauth]
neg name [type] [ttl] Add a negatively cached record to pdnsd's cache, replacing
existing records for the same name and type. If no type is
given, the whole domain is cached negatively. For
negatively cached records, errors are immediately returned
on a query, without querying other servers first. The ttl
is optional, the default is 900 seconds.
You can get a list of all types you can pass to this
command using pdnsd-ctl list-rrtypes. The type is treated
case-sensitive! Example:
pdnsd-ctl neg foo.bar A 900
pdnsd-ctl neg foo.baz 900
config [filename] Reload pdnsd's configuration file.
The config file must be owned by the uid that pdnsd had
when it was started, and be readable by pdnsd's run_as
uid. If no file name is specified, the config file used at
start-up is reloaded.
Note that some configuration changes, like the port or IP
address pdnsd listens on, cannot be made this way and you
will receive an error message. In these cases, you will
have to restart pdnsd instead.
include filename Parse the given file as an include file, see the
documentation on include sections for a description what
this file may contain.
This command is useful for adding definitions to the cache
without reconfiguring pdnsd.
eval string Parse the given string as if it were part of pdnsd's
configuration file. The string should hold one or more
complete configuration sections. However, global and
server sections are not allowed, just as in include files.
If multiple strings are given, they will be joined using
newline chars and parsed together.
This command is useful for adding records interactively to
the cache that cannot be defined using the "pdnsd-ctl add"
command, (e.g. soa records).
empty-cache [[+|-]name ...] If no arguments are provided, the cache will be completely
emptied, freeing all existing entries. Note that this also
removes local records, as defined by the config file. To
restore local records, run "pdnsd-ctl config" or
"pdnsd-ctl include filename" immediately afterwards.
The "pdnsd-ctl empty-cache" command now accepts additional
arguments; these are interpreted as include/exclude names.
If an argument starts with a '+' the name will be
included. If an argument starts with a '-' it will be
excluded. If an argument does not begin with '+' or '-', a
'+' is assumed. If the domain name of a cache entry ends
in one of the names in the list, the first match will
determine what happens. If the matching name is to be
included, the cache entry is deleted, otherwise not. If
there are no matches, the default action is not to delete.
Note that if you want to delete exactly one name and no
others, you should use "pdnsd-ctl record name delete",
this is also much more efficient.
Examples:
pdnsd-ctl empty-cache
This command will remove all cache entries.
pdnsd-ctl empty-cache microsoft.com msft.net
This will remove all entries ending in microsoft.com or
msft.net.
pdnsd-ctl empty-cache -localdomain -168.192.in-addr.arpa .
This will remove all entries except those ending in
localdomain or 168.192.in-addr.arpa. Note that '.' is the
root domain which matches any domain name.
dump [name] Print information stored in the cache about name. If name
begins with a dot and is not the root domain, information
about the names in the cache ending in name (including
name without the leading dot) will be printed. If name is
not specified, information about all the names in the
cache will be printed.
For each RR record the time and date that this record has
been added to the cache will be printed in the form mm/dd
HH:MM:SS (locally defined records are printed without a
time stamp). After that the type of record is printed with
the data. For the more common types of RR records the data
will be printed in human readable form, the remaining ones
in a hexadecimal representation.
This command is mainly useful for diagnostic purposes.
Note that if you pipe the output of this command through
an application that reads only part of the output and then
blocks (such as more or less), pdnsd will not be able to
add new entries to the cache until the pipe is closed. It
is preferable to capture the output in a file in such a
case.
list-rrtypes List available rr types for the neg command. Note that
those are only used for the neg command, not for add!
4 contrib/
The contrib directory in the pdnsd distribution contains useful
user-contributed scripts.
So far, there are scripts contributed by Marko Stolle and Paul Rombouts that
make pdnsd usable in a DHCP setup. Please take a look into the README file in
the contrib directory for further information.
5 Problems...
If you have problems with configuring or running pdnsd, be sure to read the FAQ
. If this does not help you, pdnsd crashes or you find bugs, please mail one of
the authors.
Note added by Paul A. Rombouts: Thomas Moestl no longer maintains the code. I
have revised the code and added new features. See README.par and the ChangeLog
in the source directory (or /usr/share/doc/pdnsd-<version> if you have
installed a binary package) for more details. If you have questions about my
modifications, you can find my email address at the end of README.par.
6 Hacking
Here comes some information you might find useful for hacking pdnsd.
6.1 Source files
Makefile.am, autoconf/automake/autoheader scripts. Makefile.am's are in
configure.in, most subdirectories.
acconfig.h
pdnsd.spec.in A template from which configure generates a spec file for
building rpm's for various distributions.
version Contains only the program version string. Needed for
several templates.
src/rc/* rc (start-up) scripts for various linux distributions.
The pdnsd cache subsystem(s) as defined in src/cache.h.
src/cache.c This is the "traditional" pdnsd system which keeps the
cache in memory and uses hash tables for accesses. Sourav
K. Mandal is working on a system using gdbm.
src/pdnsd-ctl/* Contains the code for pdnsd-ctl, a program that allows you
to control pdnsd at run time.
The lex/flex source file for the config file lexer. This is
src/conf-lex.l.in a template because there might be inserted "%option
yylineno" for proper flex support. (obsolete, superseded by
src/conf-parser.c)
This is automatically generated by configure from
src/conf-lex.l conf-lex.l.in. It may be overwritten in any make, so never
modify this, but conf-lex.l.in instead! (obsolete,
superseded by src/conf-parser.c)
src/conf-parse.y The yacc/bison source of the config file parser. (obsolete,
superseded by src/conf-parser.c)
src/conf-parser.c, The config file parser written purely in C (versions
src/conf-parser.h, 1.1.10-par and later).
src/conf-keywords.h
src/conff.c, src/ The configuration handler functions and their prototypes.
conff.h The parser is called from here.
src/consts.h Some constants used by the parser, config file handler
functions and in the server status thread, among others.
Define dns message structures, constants, and some common
src/dns.c, src/dns.h dns data handlers. dns.h contains gcc-specific code (in
praticular, "__attribute__((packed))").
src/dns_answer.c, Define functions that answer incoming dns queries.
src/dns_answer.h
src/dns_query.c, src Define functions to manage outgoing dns queries.
/dns_query.h
src/error.c, src/ Functions for error output to stderr or the syslog, and
error.h debug output to stderr or pdnsd.debug.
src/hash.c, src/ Contains the code for storing and looking up cache entries
hash.h in the hash table.
src/helpers.c, src/ Define miscellaneous helper functions.
helpers.h
src/icmp.c, src/ Define a function for performing a ping test. This contains
icmp.h OS-specific code.
src/main.c Contains main(), which holds the command line parser,
performs initialisations and signal handling.
Contains the code for the executable make_hashconvtable,
src/ which is only run once, during build time, to generate the
make_hashconvtable.c file hashconvtable.h, used by src/hash.c (versions
1.1.10-par and later). (obsolete since version 1.2)
A perl script for generating src/rr_types.h, a C header
src/ file containing macro definitions and tables needed for
make_rr_types_h.pl handling the RR types known to pdnsd, from the text file
src/rr_types.in.
src/rr_types.c, src/ These define tables and macros needed for handling the RR
rr_types.h, src/ types known to pdnsd. Since version 1.2.9, rr_types.h is an
rr_types.in automatically generated file, see make_rr_types_h.pl.
src/netdev.c, src/ Define functions for network device handling. OS-specific.
netdev.h
src/servers.c, src/ Define functions for the server status thread that performs
servers.h the periodical uptests.
src/status.c, src/ Define functions for the status control thread. This is
status.h pdnsd's interface to pdnsd-ctl.
-------------------------------------------------------------------------------
Copyright (C) 2000, 2001 Thomas Moestl
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2012 Paul A. Rombouts
Last revised: 19 April 2012 by Paul A. Rombouts