2631 lines
130 KiB
HTML
2631 lines
130 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>pdnsd Documentation</title>
|
|
<meta http-equiv="Content-type" content="text/html; charset=ISO-8859-1">
|
|
<style type="text/css">
|
|
<!--
|
|
.small { font-family:helvetica; font-size:small; text-align:center; }
|
|
.indented { text-indent: 2em; }
|
|
.nowrap { white-space:nowrap; }
|
|
// -->
|
|
</style>
|
|
</head>
|
|
|
|
<body bgcolor="#EEEEEE">
|
|
<!--notext(-->
|
|
<table width="100%">
|
|
<tr>
|
|
<td> <span class="small">
|
|
<a href="index.html">pdnsd Homepage</a>
|
|
</span></td>
|
|
<td> <span class="small">
|
|
<a href="faq.html">pdnsd FAQ</a>
|
|
</span></td>
|
|
<td> <span class="small">
|
|
<a href="doc.html">Documentation</a>
|
|
</span></td>
|
|
<td> <span class="small">
|
|
<a href="../../COPYING">GNU GPL (pdnsd's License)</a>
|
|
</span> </td>
|
|
<td><span class="small">
|
|
<a href="dl.html">Download Section</a>
|
|
</span></td>
|
|
</tr>
|
|
</table>
|
|
<!--)notext-->
|
|
<center><h1>pdnsd Documentation</h1></center>
|
|
This is the "official" pdnsd documentation and reference written by
|
|
<a href="index.html#authors">Thomas Moestl</a> with revisions by
|
|
<a href="index.html#authors">Paul A. Rombouts</a>.<br>
|
|
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.<br>
|
|
You can find a copy of the GNU GPL in the file <code>COPYING</code> in the source or documentation directory.<br>
|
|
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.<br>
|
|
If you want a quicker introduction to pdnsd, you can try some of the
|
|
<a href="http://www.google.com/search?q=pdnsd+howto">HOWTOs available on the web</a>.
|
|
For Apple Mac users, Brian Wells has published a good HOWTO at
|
|
<a href="http://web.mac.com/brianwells/main/pdnsd.html">http://web.mac.com/brianwells/main/pdnsd.html</a>.
|
|
|
|
|
|
<h2>0. Installation</h2>
|
|
<h3>0.1 Installing binary RPM's</h3>
|
|
To install a binary RPM, just do<br>
|
|
<p class="indented"><code>rpm -i pdnsd-<<i>version</i>>.rpm</code></p>
|
|
This should install pretty much everything automatically. The only thing left
|
|
for you to do is adapt your configuration file (stored in <code>/etc/pdnsd.conf</code>)
|
|
according to your needs (see below).
|
|
In the Red Hat and SuSE RPMs, a start script is also installed; read the section
|
|
<i>0.4, Start at Boot Time</i> about that.
|
|
|
|
<br>
|
|
<h3>0.2 Building RPM's</h3>
|
|
It is possible to build a binary RPM from a source package using the command<br>
|
|
<p class="indented"><code>rpmbuild --rebuild pdnsd-<<i>version</i>>.src.rpm</code></p>
|
|
or alternatively from a tarball using the command<br>
|
|
<p class="indented"><code>rpmbuild -tb pdnsd-<<i>version</i>>.tar.gz</code></p>
|
|
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
|
|
<a href="http://www.ibm.com/developerworks/linux/library/l-rpm1/">
|
|
http://www.ibm.com/developerworks/linux/library/l-rpm1/</a>.<br><br>
|
|
Several pdnsd-specific options are available when building RPM packages:
|
|
<table cellpadding=7>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with isdn</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--enable-isdn</code> (<a href="#enableisdn">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--without poll</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--disable-poll</code> (<a href="#disablepoll">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--without nptl</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--with-thread-lib=linuxthreads</code> (<a href="#threadlib">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with ipv6</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--enable-ipv6</code> (<a href="#enableipv6">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--without tcpqueries</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--disable-tcp-queries</code> (<a href="#disabletcpqueries">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--without debug</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--with-debug=0</code> (<a href="#withdebug">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--define "distro <<i>distro</i>>"</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--with-distribution=<<i>distro</i>></code> (<a href="#withdistro">see below</a>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--define "run_as_user <<i>user</i>>"</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--with-default-id=<<i>user</i>></code> (<a href="#defaultid">see below</a>).<br>
|
|
For RPMs the default <code><<i>user</i>></code> is <code>"pdnsd"</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--define "run_as_uid <<i>uid</i>>"</code>
|
|
</td>
|
|
<td>
|
|
If the user defined by the previous option does not exist when the RPM is installed,
|
|
the pre-install script will try to create a new user with numerical id <code><<i>uid</i>></code>.
|
|
The default is to let the system choose the numerical id at install time.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--define "cachedir <<i>dir</i>>"</code>
|
|
</td>
|
|
<td>
|
|
Has the same effect as <code>--with-cachedir=<<i>dir</i>></code> (<a href="#withcachedir">see below</a>).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
You can also configure which compiler flags will be used by setting the environment variable
|
|
<code>CFLAGS</code>.
|
|
Using a bash shell, you can do that on the command line like this:
|
|
<code> CFLAGS="-O1 -Wall" rpmbuild ...</code><br>
|
|
This is useful if you prefer a different level of optimization, for instance.
|
|
|
|
<br>
|
|
<h3>0.3 Installing from pure sources (tar archives or git repositories)</h3>
|
|
<h4>0.3.1 Setting up the source code tree</h4>
|
|
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.
|
|
<h5>0.3.1.1 Unpacking a tar archive</h5>
|
|
The pdsnsd snapshot releases come in the form of a gzip'ed tar archive.
|
|
To decompress it (using a modern tar) do<br>
|
|
<p class="indented"><code>tar -xzf pdnsd-<version>.tar.gz</code></p>
|
|
If your tar doesn't do this, use:<br>
|
|
<p class="indented"><code>gzip -dc pdnsd-<version>.tar.gz | tar -xf -</code></p>
|
|
<h5>0.3.1.2 Cloning a git repository</h5>
|
|
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:<br>
|
|
<p class="indented"><code>git clone git://gitorious.org/pdnsd/pdnsd.git pdnsd</code></p>
|
|
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 <a href="http://gitorious.org/pdnsd">gitorious.org</a> website or git documentation for more information.
|
|
|
|
<h4>0.3.2 Configuring the source</h4>
|
|
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):<br>
|
|
<table bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--prefix=<i>dir</i></code>
|
|
</td>
|
|
<td>
|
|
Specify the prefix directory. The pdnsd files are installed in subdirectories
|
|
of the prefix, the pdnsd and pdnsd-ctl executables are for example installed
|
|
in the sbin subdirectory of the prefix. The default for this is /usr/local;
|
|
you might want to set this to /usr (using <code>--prefix=/usr</code>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--sysconfdir=<i>dir</i></code>
|
|
</td>
|
|
<td>
|
|
Specify the config directory. pdnsd expects its pdnsd.conf file to reside
|
|
there if the <code>-c</code> option is not given at startup.
|
|
The default for this is the <code>etc</code> subdirectory of your prefix, e.g. <code>/usr/local/etc</code>
|
|
if you did not specify a prefix. To set this e.g. to <code>/etc</code>, use <code>--sysconfdir=/etc</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="withdistro">--with-distribution=<i>distro</i></a></code>
|
|
</td>
|
|
<td>
|
|
Specify target distribution (default=Generic; others: RedHat, SuSE, Debian)<br>
|
|
See below for the effect of these settings.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-target=<i>platform</i></code>
|
|
</td>
|
|
<td>
|
|
Change compilation target platform (default: autodetect; others: Linux, BSD, Cygwin).<br>
|
|
autodetect will attempt to detect whether you are using Linux, *BSD or Cygwin and
|
|
should normally be sufficient. If this does not work, try specifying
|
|
your system manually (for the Darwin platform (Apple Mac OS X) specify BSD here).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="withcachedir">--with-cachedir=<i>dir</i></a></code>
|
|
</td>
|
|
<td>
|
|
Default directory for pdnsd cache (default=/var/cache/pdnsd)<br>
|
|
This setting can be changed via config file settings when pdnsd has been built.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-hash-buckets=<i>num</i></code>
|
|
</td>
|
|
<td>
|
|
Number of hash buckets to use (default=1024). The default should be
|
|
sufficient for most purposes, but if you want to store a large number of names
|
|
in the cache, cache lookups may be faster if the number of hash buckets
|
|
is comparable to the number of names stored in the cache.
|
|
The number actually used is the smallest power of two
|
|
greater or equal to the number specified here.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="enableisdn">--enable-isdn</a></code>
|
|
</td>
|
|
<td>
|
|
Enable ISDN support<br>
|
|
This option will work only on Linux and may cause problems with 2.0.x or
|
|
old 2.2.x kernels. You will need it for a proper <code>if</code> uptest
|
|
under Linux for ISDN ppp devices.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-ipv4</code>
|
|
</td>
|
|
<td>
|
|
Disable IPv4 networking support (default=enabled)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="enableipv6">--enable-ipv6</a></code>
|
|
</td>
|
|
<td>
|
|
Enable IPv6 networking support.<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-ipv4-startup</code>
|
|
</td>
|
|
<td>
|
|
Disable IPv4 on pdnsd startup by default (default=enabled)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--enable-ipv6-startup</code>
|
|
</td>
|
|
<td>
|
|
Enable IPV6 on pdnsd startup by default (default=IPv4).
|
|
These options are only defaults, you can specify on
|
|
the command line or in the config files which IP version
|
|
will really be used.
|
|
Normally, you won't need to change these.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-udp-queries</code>
|
|
</td>
|
|
<td>
|
|
Disable UDP as query method. You shouldn't need to change
|
|
this.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="disabletcpqueries">--disable-tcp-queries</a></code>
|
|
</td>
|
|
<td>
|
|
Disable TCP as query method. This only effects the querying of
|
|
name servers by pdnsd, not the ability of pdnsd to answer
|
|
TCP queries from clients.
|
|
TCP queries are slower than UDP queries, but can be more secure
|
|
against certain types of attacks and are able to handle large answers.
|
|
For normal use this can be disabled.
|
|
(Note that the default has changed: TCP-query support
|
|
is now compiled in by default, but it still depends on the run-time
|
|
options whether it is actually used.)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-query-method=<i>qm</i></code>
|
|
</td>
|
|
<td>
|
|
Specify the query method (default=udponly, others: tcponly, tcpudp, udptcp).
|
|
If you have enabled both UDP and TCP queries, this lets you control
|
|
which query method pdnsd will use by default. tcpudp will try TCP
|
|
first and fall back to UDP if TCP is not supported by the server;
|
|
udptcp will try UDP first and, if the answer was truncated, will repeat
|
|
the query using TCP.
|
|
udponly and tcponly should be clear. Note that this only effects
|
|
the compiled-in default; the query method can still be changed using
|
|
command-line options or options in the configuration file.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-tcp-server</code>
|
|
</td>
|
|
<td>
|
|
Disable the TCP server.
|
|
In this case pdnsd will not be able to respond to TCP queries from clients.
|
|
This may cause problems with very large answers.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-src-addr-disc</code>
|
|
</td>
|
|
<td>
|
|
Disable the UDP source address discovery.<br>
|
|
You need this only if you have trouble with messages saying
|
|
"could not discover udp source address".<br>
|
|
For the Cygwin target, this option is disabled by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="disablepoll">--disable-poll</a></code>
|
|
</td>
|
|
<td>
|
|
Disable poll(2) and use select(2) (default=enabled)<br>
|
|
You will normally not need this.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--disable-new-rrs</code>
|
|
</td>
|
|
<td>
|
|
Since version 1.2.9 this option is obsolete and ignored.
|
|
It is now possible to configure for each RR type separately whether it is
|
|
cacheable by pdnsd by editing the file <code>src/rr_types.in</code>.
|
|
The comments in this file explain how to do this.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--enable-strict-rfc2181</code>
|
|
</td>
|
|
<td>
|
|
Enforce strict RFC 2181 compliance.<br>
|
|
This will cause pdnsd to reject DNS answers with incorrect
|
|
timestamp settings (multiple RRs of the same type and for the same domain with
|
|
different TTLs). Normally not needed.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="enableunderscores">--enable-underscores</a></code>
|
|
</td>
|
|
<td>
|
|
This option is obsolete. Since version 1.2, pdnsd places no restrictions
|
|
on the types of characters in domain names (there are still a few restrictions
|
|
for locally defined names, though).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-random-device=<i>device</i></code>
|
|
</td>
|
|
<td>
|
|
Specify random device; default: C Library <code>random()</code> PRNG<br>
|
|
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
|
|
<code>random()</code> function, which is relatively weak.
|
|
You can specify a device like /dev/urandom here if you like; pdnsd will read
|
|
random numbers from it 16-bit-wise. /dev/urandom is present under Linux and
|
|
most BSD derivates. You should not use /dev/random - it is more secure, but
|
|
may block and delay pdnsd's answers for a long time.<br>
|
|
You can specify <code>arc4random</code> to use the BSD <code>arc4random()</code>
|
|
library function (default for FreeBSD target), which is considered safe.<br>
|
|
You can also specify <code>random</code> as device to use the C Library
|
|
<code>random()</code> function (described above).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="defaultid">--with-default-id=<i>user</i></a></code>
|
|
</td>
|
|
<td>
|
|
Specify default user for pdnsd (default=nobody).
|
|
This is the user that will be entered for the <code>run_as</code>
|
|
option in the config file (see <a href="#runas">below</a>) that will be installed during <code>make install</code>.
|
|
You can change this any time in your config file.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="withdebug">--with-debug=<i>level</i></a></code>
|
|
</td>
|
|
<td>
|
|
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.<br>
|
|
Presently the only defined debug levels are in the range 0 - 9.
|
|
Setting the level to 9 enables hex dumps of the queries and replies
|
|
pdnsd receives and should normally not be needed. Debug output will only
|
|
be generated if you turn on special switches; it might be useful for
|
|
debugging your config files, so I recommend using the default (1).
|
|
However, if you use pdnsd under heavy load, a better strategy may be
|
|
to compile one version of pdnsd without debug support (configured with
|
|
<code>--with-debug=0</code>) for production use, and one version with
|
|
with debug support (e.g. <code>--with-debug=9</code>)
|
|
for diagnostic purposes.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-verbosity=<i>level</i></code>
|
|
</td>
|
|
<td>
|
|
Specify default message verbosity. The default should be ok.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--enable-rcsids</code>
|
|
</td>
|
|
<td>
|
|
Enable RCS IDs in executables (default=disabled).<br>
|
|
For personal use, there is no need to do this. If you build rpm's, it
|
|
might have advantages.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--enable-tcp-subseq</code>
|
|
</td>
|
|
<td>
|
|
Enable subsequent tcp queries. The DNS protocol standard
|
|
requires that servers must be capable of answering multiple
|
|
subsequent queries that are sent over the same tcp connection, and that
|
|
the server may only close the connection by himself after a certain
|
|
timeout. This feature is rarely used, but may make denial-of-service
|
|
attacks easier, as it allows for an attacker to hold a connection open
|
|
a long time (although the attacker's IP is most likely revealed then).
|
|
For full standard compliance, you should use this option.
|
|
If you do not use <code>--enable-tcp-server</code>, is option is not honored.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-tcp-qtimeout=<i>secs</i></code>
|
|
</td>
|
|
<td>
|
|
Specify default tcp query timeout after which the connection is closed
|
|
if no full query has been received. The default is 30s.
|
|
You can also change this option at run time using the tcp_qtimeout
|
|
config file option.
|
|
If you do not use <code>--enable-tcp-server</code>, is option is not honored.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-par-queries=<i>num</i></code>
|
|
</td>
|
|
<td>
|
|
Specify the default number of queries that can be executed in parallel.
|
|
You can also change this option at run time using the par_queries
|
|
config file option. See the description of that option for an explanation
|
|
of what it really does.<br>
|
|
The default for this option is 2.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code>--with-max-nameserver-ips=<i>num</i></code>
|
|
</td>
|
|
<td>
|
|
<em>New in version 1.2.9b:</em>
|
|
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 was the strategy used by pdnsd in previous 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.<br>
|
|
The default for this option is 3.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">
|
|
<code><a name="threadlib">--with-thread-lib=<i>lib</i></a></code>
|
|
</td>
|
|
<td>
|
|
<em>Added by Paul Rombouts</em>: 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 <code>/var/cache/pdnsd/pdnsd.cache</code> remains empty.
|
|
If you experience this kind of trouble, try reconfiguring with different values
|
|
for the <code>--with-thread-lib</code> option. The allowable values are
|
|
<code>linuxthreads</code> (or <code>lt</code> for short), <code>linuxthreads2</code>
|
|
(or <code>lt2</code> for short), and <code>nptl</code>.
|
|
By default the configure script tries to detect automatically whether
|
|
<code>linuxthreads</code> or <code>nptl</code> is more appropriate for your system,
|
|
but the method used is not foolproof. Look for the line:
|
|
<code>checking if this is an NPTL-based system...</code><br>
|
|
If the automatic test mistakenly indentifies the thread library on your system as
|
|
NPTL based, you should reconfigure with <code>--with-thread-lib=lt</code> and recompile.
|
|
If the result of the automatic test is "<code>no</code>" or if
|
|
<code>--with-thread-lib=lt</code> does not have the desired effect, try again using
|
|
<code>--with-thread-lib=lt2</code> .
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
Normally, you will need only <code>--prefix</code>, <code>--sysconfdir</code> and
|
|
<code>--with-distribution</code>.
|
|
If you specify your distribution using <code>--with-distribution</code>, this has the
|
|
following effects:
|
|
<ul>
|
|
<li> An rc script is copied in the appropriate localtion, which enables pdnsd to start
|
|
at machine boot time (see 0.4)
|
|
<li> Distribution-specific portions might be included in the generated pdnsd.spec
|
|
file (only important if you want to build rpm archives yourself).
|
|
</ul>
|
|
If you choose <code>Generic</code>, no rc script is installed, and a generic spec
|
|
file is generated.<br>
|
|
|
|
Further instructions are in the INSTALL document in the pdnsd source directory.
|
|
<code>./configure --help</code> will give you a list of all supported command line
|
|
options.<br><br>
|
|
<em>Note added by Paul Rombouts</em>: Some people may want change the compiler optimization flag.
|
|
I use the <code>-O2</code> flag, but it might be safer to use a lower level of
|
|
optimization or no optimization at all. In that case prefix the
|
|
<code>configure</code> command with the desired compiler flags like this
|
|
(assuming you're using a bash shell):
|
|
<p class="indented"><code>CFLAGS="-O1 -Wall" ./configure ...</code></p>
|
|
|
|
|
|
<br>
|
|
<h4>0.3.3 Building & installing </h4>
|
|
Type <code>make</code> in the source directory. <i>Should</i> work by now.<br>
|
|
To install, type <code>make install</code> or do the installation by hand (see <i>0.3.4</i>).<br>
|
|
<code>make install</code> will do the following ($prefix is the prefix directory; see above):<br>
|
|
<ol>
|
|
<li> copies pdnsd to <code>$(prefix)/sbin/</code>
|
|
<li> copies pdnsd-ctl to <code>$(prefix)/sbin/</code>
|
|
<li> copies docs/pdnsd.conf.sample (a sample configuration) to the pdnsd config directory.
|
|
<li> creates your cache directory if it is not there.
|
|
After installation, you should check the file permissions and create or edit
|
|
<code>/etc/pdnsd.conf</code> to fit your needs (see below).
|
|
If you use the <a href="#runas"><code>run_as</code></a> option, please make sure that your
|
|
cache directory is owned by the user you specified with this option!
|
|
</ol>
|
|
You must be root for this installation!<br>
|
|
<b>Security notes:</b> <b><i>never</i></b> 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.<br>
|
|
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.
|
|
<br>
|
|
<h4>0.3.4 Manual installation </h4>
|
|
For a manual installation, you need to do the following steps:
|
|
<ol>
|
|
<li> Copy pdnsd and pdnsd-ctl from your build directory to an appropriate location (e.g. <code>/usr/sbin</code>).
|
|
<li> Copy <code>docs/pdnsd.conf</code> into the directory you want it to reside (<code>/etc</code> by default,
|
|
and change it according to your needs (see below).
|
|
<li> Create your caching directory; default is <code>/var/cache/pdnsd</code> (you may change this
|
|
in your <code>pdnsd.conf</code>); Permissions should be at max <code>rwxr-xr-x</code> (if you want to
|
|
protect your cache and status socket, make it <code>rwx------</code>).
|
|
</ol>
|
|
Thats it!
|
|
<br>
|
|
|
|
<h3>0.4 Start at boot time</h3>
|
|
In the <code>src/rc</code> 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.<br>
|
|
The start scripts are automatically installed during RPM install, and also during <code>make install</code>
|
|
if you specified your distro.<br>
|
|
For Slackware Linux there is a start-up script contributed by Nikola Kotur, but presently
|
|
it must be installed manually.
|
|
See <code>src/rc/README</code> and <code>src/rc/Slackware/rc.pdnsd</code> for details.
|
|
|
|
<h4>0.4.1 SuSE Linux startup</h4>
|
|
<code>rc/SuSE/pdnsd</code> is a start script for SuSE Linux. It was tested for 6.? but should run on some
|
|
versions below. You can do <code>make install</code> as root in the <code>rc/SuSE</code>
|
|
directory to install it, or you can install manually:<br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=5>
|
|
<tr>
|
|
<td>
|
|
<b>manual installation</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
For manual installation, copy <code>rc/SuSE/pdnsd</code> into <code>/sbin/init.d/</code>, go to
|
|
<code>/sbin/init.d/rc2.d/</code> and create there the following two symlinks:<br>
|
|
S11pdnsd to ../pdnsd (do <code>ln -s ../pdnsd S11pdnsd</code> in that dir) <br>
|
|
K34pdnsd to ../pdnsd (do <code>ln -s ../pdnsd K34pdnsd</code> in that dir) <br>
|
|
The numbers dictate the order different services are started and
|
|
might need to be modified. Then edit your <code>/etc/rc.config</code> file and
|
|
add the line <code>START_PDNSD=yes</code> to start pdnsd at boot time.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
If you used the <code>make install</code> command, <code>START_PDNSD=yes</code> has been
|
|
appended to your <code>/etc/rc.config</code> file, causing pdnsd to be started
|
|
at boot time. If you don't want that, change the <code>yes</code> into <code>no</code>.
|
|
</p>
|
|
This start script was created from <code>/sbin/init.d/skeleton</code> by me, so the
|
|
most is copyrighted by SuSE. They put it under the GPL, however, so
|
|
the license stated in <a href="../../COPYING">COPYING</a> 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.
|
|
<h4>0.4.2 Red Hat Linux startup</h4>
|
|
<code>rc/Redhat/pdnsd</code> is a start script for Red Hat Linux. It was contibuted by Torben
|
|
Janssen. <br>
|
|
This was tested for 6.1 but should run on 5.0+. You can do <code>make install</code> as root in the
|
|
<code>rc/Redhat</code> directory to install it, or you can install manually:<br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=5>
|
|
<tr>
|
|
<td>
|
|
<b>manual installation</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
For manual installation, copy <code>rc/Redhat/pdnsd</code> into <code>/etc/rc.d/init.d/</code><br>
|
|
Then go to <code>/etc/rc.d/rc3.d</code> and create there the following symlink:<br>
|
|
S78pdnsd -> ../init.d/pdnsd
|
|
(do <code>ln -f -s ../init.d/pdnsd S78pdnsd</code> in that dir)<br>
|
|
|
|
Then go to <code>/etc/rc.d/rc0.d</code> and create there the following symlink:<br>
|
|
K78pdnsd -> ../init.d/pdnsd
|
|
(do <code>ln -f -s ../init.d/pdnsd K78pdnsd</code> in that dir)<br>
|
|
|
|
Then go to /etc/rc.d/rc6.d and create there the following symlink:<br>
|
|
K78pdnsd -> ../init.d/pdnsd
|
|
(do <code>ln -f -s ../init.d/pdnsd K78pdnsd</code> in that dir)
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
This script is also covered by license stated in <a href="../../COPYING">COPYING</a>.
|
|
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
|
|
<br>
|
|
<h3>0.5 Notes for FreeBSD users</h3>
|
|
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.<br>
|
|
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.<br>
|
|
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.<br>
|
|
<br>
|
|
<br>
|
|
<h2>1 Invocation</h2>
|
|
When invoking pdnsd, you can specify various options at the command line. Command line options
|
|
always override config file options. The various <b>--noX</b> options are present to override
|
|
config file options.
|
|
<p>
|
|
pdnsd <b>--help</b> (or <b>-h</b>) gives you an overview of the pdnsd command line options.
|
|
</p>
|
|
<p>
|
|
pdnsd <b>--version</b> (or <b>-V</b> for short) prints licence and version information.
|
|
</p>
|
|
<p>
|
|
To start pdnsd as background daemon, specifiy <b>--daemon</b> (or <b>-d</b> 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. <b>--nodaemon</b> will disable this.
|
|
</p>
|
|
<p>
|
|
When starting pdnsd as a daemon, the <b>-p</b> option may be helpful: It writes the pid
|
|
of the server process to the file of the name given as argument to this option. <br>
|
|
Example: <code>pdnsd -d -p /var/run/pdnsd.pid</code>
|
|
</p>
|
|
<p>
|
|
If you want to specify a configuration file other than <code>/etc/pdnsd.conf</code>, specify
|
|
<b>-c</b> or <b>--config-file</b> on the command line, followed by a filename.
|
|
</p>
|
|
<p>
|
|
If pdnsd was compiled with debugging support, you may specify <b>-g</b> or
|
|
<b>--debug</b> 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 <code>pdnsd.debug</code>
|
|
file in your cache directory. <b>--nodebug</b> disables debugging.
|
|
</p>
|
|
<p>
|
|
pdnsd <b>-v</b><i>n</i> sets the verbosity level of pdnsd. <i>n</i> 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 <code>--debug</code> option for very
|
|
extensive debug information.<br>
|
|
<i>Note</i>: The current implementation mostly ignores the verbosity level,
|
|
so you may not notice much difference between the various levels.
|
|
</p>
|
|
<p>
|
|
The option <b>-s</b> or <b>--status</b> enables the status control socket. This is a named socket in
|
|
the cache directory called <code>pdnsd.status</code>. This socket allows run-time configuration of pdnsd
|
|
using the utility <code>pdnsd-ctl</code>. See <a href="#pdnsdctl">below</a> for more details about <code>pdnsd-ctl</code>.
|
|
<b>--nostatus</b> disables status control.
|
|
See also the configuration option <a href="#statusctl"><code>status_ctl</code></a> in the global section.
|
|
</p>
|
|
<p>
|
|
The option <b>--notcp</b> disables the seldom needed TCP server thread, which may
|
|
save you some resources. <b>-t</b> or <b>--tcp</b> will enable it.
|
|
See also the <a href="#tcpserver"><code>tcp_server</code></a> configuration option.
|
|
</p>
|
|
<p>
|
|
Using the <a name="querymethodcommandlineoption"><b>-m</b></a> option, you can select the method pdnsd uses to query other name servers.
|
|
Following methods are supported (see also the <a href="#querymethod"><code>query_method</code></a>
|
|
configuration option):<br>
|
|
<b>-muo</b>: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers
|
|
on the Internet. <br>
|
|
<b>-mto</b>: 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.<br>
|
|
<b>-mtu</b>: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused or times out.<br>
|
|
<b>-mut</b>: <em>New in version 1.2.5:</em> pdnsd will try to use UDP, and will repeat the query using TCP if the UDP reply was truncated
|
|
(i.e. the <code>tc</code> bit is set). This is the behaviour recommended by the DNS standards.<br>
|
|
</p>
|
|
<p>
|
|
The <b>-4</b> option switches to IPv4 mode, providing pdnsd was compiled with IPv4 support.<br>
|
|
The <b>-6</b> option switches to IPv6 mode, providing pdnsd was compiled with IPv6 support.<br>
|
|
The <b>-a</b> 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.<br>
|
|
</p>
|
|
<p>
|
|
With <b>-i</b> <em>prefix</em> or <b>--ipv4_6_prefix=</b><em>prefix</em> 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, <a href="#ipv46prefix">see below</a>.
|
|
Must be a valid IPv6 address.
|
|
The default is <code>::ffff:0.0.0.0</code>
|
|
</p>
|
|
|
|
<h2>2 The configuration file</h2>
|
|
This section describes the layout of the configuration file and the available
|
|
configuration options.
|
|
The default location of the file is <code>/etc/pdnsd.conf</code>. 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 <code>/etc/</code> by <code>make install</code>.
|
|
|
|
<br>
|
|
<h3>2.1 Layout</h3>
|
|
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
|
|
<br><code>
|
|
<i>option_name</i>=<i>option_value</i>;
|
|
</code><br>
|
|
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 "<code>,;{}\</code>".
|
|
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. <code>\t</code> becomes a tab,
|
|
<code>\n</code> becomes a new-line control char.<br>
|
|
A time specification consists a sequence of digits followed by a one-letter suffix.
|
|
The following suffixes are recognized:
|
|
<code>s</code> (seconds), <code>m</code> (minutes), <code>h</code> (hours),
|
|
<code>d</code> (days) and <code>w</code> (weeks).
|
|
If the suffix is missing, seconds are assumed.
|
|
If several time specifications are concatenated, their values are added together;
|
|
e.g. <code>2h30m</code> is interpreted as 2*60*60 + 30*60 = 9000 seconds.<br>
|
|
Some options take more than one value; in this case, the values are separated with commas.<br>
|
|
If you may supply one of a set of possible values to an option, this is noted
|
|
in the documentation as
|
|
<code>(option1|option2|option3|...)</code><br>
|
|
The constants <code>true|false</code> and <code>yes|no</code>
|
|
are accepted as synonyms for the constants <code>on|off</code>.<br>
|
|
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.<br>
|
|
There are examples for nearly all options in the sample config file.
|
|
<br>
|
|
<h3>2.1.1 <a name="globalsection"><code>global</code> Section</a></h3>
|
|
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.<br>
|
|
These are the possible options:<br><br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>perm_cache=(<i>number</i>|off);</code></b><br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>cache_dir=<i>string</i>;</code></b><br>
|
|
Set the directory you want to keep the cache in.
|
|
The default is <code>"/var/cache/pdnsd"</code>
|
|
(unless pdnsd was compiled with a different default).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>server_port=<i>number</i>;</code></b><br>
|
|
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.<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>server_ip=<i>string</i>;</code></b><br>
|
|
or<br>
|
|
<b><code>interface=<i>string</i>;</code></b><br>
|
|
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 <code>server_ip=any</code>, 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 <code>server_ip=any</code>
|
|
and use firewall rules to restrict access.<br>
|
|
The IP address used to need quotation marks around it, but since version 1.1.10
|
|
this is no longer necessary.<br>
|
|
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 <code>-6</code> command-line option or
|
|
set <code>run_ipv4=off</code> first (see <a href="#runipv4">below</a>) in order to ensure that the
|
|
IPv6 address is parsed correctly.<br>
|
|
If pdnsd is running in IPv6 mode and you specify an IPv4 address here,
|
|
it will automatically be mapped to an IPv6 address.<br>
|
|
<em>New in version 1.2:</em> You may also give the name of an interface
|
|
such as <code>"lo"</code> or <code>"eth0"</code> 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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>outgoing_ip=<i>string</i>;</code></b><br>
|
|
or<br>
|
|
<b><code>outside_interface=<i>string</i>;</code></b><br>
|
|
<em>New in version 1.2.9:</em>
|
|
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 <code>server_ip=192.168.1.1</code>
|
|
and <code>outgoing_ip=123.xxx.yyy.zzz</code> 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.<br>
|
|
The default setting for this option is <code>any</code>, which means that
|
|
the kernel is free to decide which interface to use.
|
|
Like with the <code>server_ip</code> option, you may also give the name of an
|
|
interface here, instead of an IP address.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>linkdown_kluge=(on|off);</code></b><br>
|
|
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 <code>rr</code> and <code>source</code>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>max_ttl=<i>timespec</i>;</code></b><br>
|
|
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 <code>max_ttl</code>, this time to live value is set to <code>max_ttl</code>.
|
|
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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>min_ttl=<i>timespec</i>;</code></b><br>
|
|
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 <code>min_ttl</code>, this time to live value is set to <code>min_ttl</code>.
|
|
Default is 120 seconds.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>neg_ttl=<i>timespec</i>;</code></b><br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>neg_rrs_pol=(on|off|auth|default);</code></b><br>
|
|
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. <code>off</code> will
|
|
turn the negative caching of record types off, <code>on</code> will always add a negative
|
|
cache entry when a name server did not return a record type we asked it for, and <code>auth</code>
|
|
will only add such entries if the answer came from an authoritative name server for that
|
|
domain.<br>
|
|
<em>New in version 1.2.8:</em> The <code>default</code> 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.<br>
|
|
The preset is "<code>default</code>" (used to be <code>auth</code>).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>neg_domain_pol=(on|off|auth);</code></b><br>
|
|
This is analogue to <code>neg_rrs_pol</code> for whole domain negative caching. It should be safe
|
|
to set this <code>on</code>, because I have not seen a caching server that will falsely claim that a
|
|
domain does not exist.<br>
|
|
The default is <code>auth</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="runas">run_as=<i>string</i>;</a></code></b><br>
|
|
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. <br>
|
|
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 <code>off</code> (see below, <code>on</code> 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.<br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>strict_setuid=(on|off);</code></b><br>
|
|
When used together with the <code>run_as</code> option, this option lets you specify that all threads of the
|
|
program will run with the privileges of the <code>run_as</code> user. This provides higher security than
|
|
the normal <code>run_as</code>
|
|
option, but is not always possible. See the <a href="#runas"><code>run_as</code></a> option for further discussion.<br>
|
|
This option is on by default.<br>
|
|
Note that this option has no effect on Non-Linux systems.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>paranoid=(on|off);</code></b><br>
|
|
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.<br>
|
|
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same
|
|
operation.<br>
|
|
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.<br>
|
|
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).<br>
|
|
The <code>paranoid</code> option is off by default.<br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ignore_cd=(on|off);</code></b><br>
|
|
<em>New in version 1.2.8:</em> 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.<br>
|
|
This option is on by default. Turn it off if you want the old behaviour (before version 1.2.8).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>scheme_file=<i>string</i>;</code></b><br>
|
|
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 <code>/var/lib/pcmcia/scheme</code> or
|
|
<code>/var/state/pcmcia/scheme</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="statusctl">status_ctl=(on|off);</a></code></b><br>
|
|
This has the same effect as the <code>-s</code> command line option: the status control is enabled when
|
|
<code>on</code> is specified.<br>
|
|
<em>Added by Paul Rombouts</em>: Note that <code>pdnsd-ctl</code> allows run-time configuration of pdnsd,
|
|
even the IP addesses of the name servers can be changed. If you're not using <code>pdnsd-ctl</code> and
|
|
you want maximum security, you should not enable this option. It is disabled by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>daemon=(on|off);</code></b><br>
|
|
This has the same effect as the <code>-d</code> command line option: the daemon mode is enabled when
|
|
<code>on</code> is specified.<br>
|
|
Default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="tcpserver">tcp_server=(on|off);</a></code></b><br>
|
|
<code>tcp_server=on</code> has the same effect as the <code>-t</code> or <code>--tcp</code>
|
|
command-line option: it enables TCP serving.
|
|
Similarly, <code>tcp_server=off</code> is like the <code>--notcp</code> command-line option.<br>
|
|
Default is <code>on</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>pid_file=<i>string</i>;</code></b><br>
|
|
This has the same effect as the <code>-p</code> command line option: you can specify a file that pdnsd
|
|
will write its pid into when it starts in daemon mode.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>verbosity=<i>number</i>;</code></b><br>
|
|
This has the same effect as the <code>-v</code> 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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="querymethod">query_method=(tcp_only|udp_only|tcp_udp|udp_tcp);</a></code></b><br>
|
|
This has the same effect as the <code>-m</code> command line option.
|
|
Read the documentation for the <a href="#querymethodcommandlineoption">command line option</a> on this.
|
|
<code>tcp_only</code> corresponds to the <code>to</code>, <code>udp_only</code> to the <code>uo</code>,
|
|
<code>tcp_udp</code> to the <code>tu</code> and <code>udp_tcp</code> to the <code>ut</code>
|
|
argument of the command line option.<br>
|
|
If you use <code>query_method=tcp_udp</code>, it is recommended that you also set the <a href="#globaltimeout">global timeout option</a> to at least twice the longest server timeout.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="runipv4">run_ipv4=(on|off);</a></code></b><br>
|
|
This has the same effect as the <code>-4</code> or <code>-6</code> 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 <code>run_ipv4=off</code> first to
|
|
ensure that the IPv6 addresses are parsed correctly.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>debug=(on|off);</code></b><br>
|
|
This has the same effect as the <code>-g</code> command line option: the debugging messages are enabled when
|
|
<code>on</code> is specified.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ctl_perms=<i>number</i>;</code></b><br>
|
|
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).<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>proc_limit=<i>number</i>;</code></b><br>
|
|
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 <code>procq_limit</code> option.<br>
|
|
The default for this option is 40.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>procq_limit=<i>number</i>;</code></b><br>
|
|
When the query thread limit <code>proc_limit</code> 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.<br>
|
|
See also the <code>proc_limit</code> option. A maximum of <code>proc_limit+procq_limit</code>
|
|
query threads will exist at any one time (plus 3 to 6 threads that will always
|
|
be present depending on your configuration).<br>
|
|
The default for this option is 60.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>tcp_qtimeout=<i>timespec</i>;</code></b><br>
|
|
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
|
|
<code>--with-tcp-qtimeout</code> option to <code>configure</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>par_queries=<i>number</i>;</code></b><br>
|
|
This option used to set the maximum number of remote servers that would be queried simultaneously,
|
|
for every query that pdnsd receives.<br>
|
|
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 <i>server1, server2, server3,</i> etc. of available servers
|
|
and <code>par_queries=2</code>, then pdnsd will first send queries to <i>server1</i> and <i>server2</i>,
|
|
and listen for responses from these servers.<br>
|
|
If these servers do not send a reply within their timeout period, pdnsd will send additional
|
|
queries to <i>server3</i> and <i>server4</i>, and listen for responses from
|
|
<i>server1, server2, server3</i> and <i>server4</i>, and so on until a useful reply is
|
|
received or the list is exhausted.<br>
|
|
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.<br>
|
|
See also the explanation of the global timeout option below.<br>
|
|
1 or 2 are good values for this option.
|
|
The default is set at compile time using the <code>--with-par-queries</code> option to <code>configure</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="globaltimeout">timeout=<i>timespec</i>;</a></code></b><br>
|
|
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.<br>
|
|
If you use <code>query_method=tcp_udp</code> 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.<br>
|
|
Default value is 0.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>randomize_recs=(on|off);</code></b><br>
|
|
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.<br>
|
|
On by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="queryportstart">query_port_start=(<i>number</i>|none);</a></code></b><br>
|
|
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 <a href="#queryportend"><code>query_port_end</code></a>) used for queries.
|
|
pdnsd will try to randomly select a free port from this range as local port for the query.<br>
|
|
To ensure that there are enough ports for pdnsd to use, the range between <code>query_port_start</code> and
|
|
<code>query_port_end</code> should be adjusted to at least (<code>par_queries</code> * <code>proc_limit</code>).
|
|
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.<br>
|
|
The default for this option is 1024. Together with the default value of <code>query_port_end</code>,
|
|
this makes it the hardest for an attacker to guess the source port used by the pdnsd resolver.
|
|
If you specify <code>none</code> here, pdnsd will let the kernel choose the source port, but
|
|
this may leave pdnsd more vulnerable to an attack.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="queryportend">query_port_end=<i>number</i>;</a></code></b><br>
|
|
Used if <code>query_port_start</code> is not <code>none</code>. 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 <a href="#queryportstart"><code>query_port_start</code></a>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="delegationonly">delegation_only=<i>string</i>;</a></code></b><br>
|
|
<em>Added by Paul Rombouts</em>: 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 <a href="#serversection"><code>server</code></a> section it is
|
|
important that you set <code><a href="#rootserver">root_server</a>=on</code> in such a section.<br>
|
|
Example:
|
|
<p class="indented"><code>delegation_only="com","net";</code></p>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="ipv46prefix">ipv4_6_prefix=<i>string</i>;</a></code></b><br>
|
|
This option has the same effect as the <code>-i</code> 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 <a href="#pdnsdctl"><code>pdnsd-ctl</code></a>)
|
|
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.<br>
|
|
The default is <code>"::ffff.0.0.0.0"</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>use_nss=(on|off);</code></b><br>
|
|
If this option is turned on, pdnsd will call <code>initgroups()</code> to set up the group access list,
|
|
whenever pdnsd changes its user and group id (see <a href="#runas"><code>run_as</code></a> option).
|
|
There is a possible snag, though, if <code>initgroups()</code> uses NSS (Name Service Switch) and
|
|
NSS in turn uses DNS. In such a case you may experience lengthy timeouts and stalls.
|
|
By setting <code>use_nss=off</code>, you can disable the <code>initgroups()</code> call
|
|
(only possible in versions 1.2.5 and later).<br>
|
|
This option was contributed by Jan-Marek Glogowski.<br>
|
|
On by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="udpbufsize">udpbufsize=<i>number</i>;</a></code></b><br>
|
|
<em>New in version 1.2.9:</em>
|
|
This option sets the upper limit on the size of UDP DNS messages. The default is 1024.<br>
|
|
See also the <code><a href="#ednsquery">edns_query</a></code> server option below.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3>2.1.2 <a name="serversection"><code>server</code> Section</a></h3>
|
|
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.<br>
|
|
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.<br>
|
|
The supported options in this section are:<br><br>
|
|
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>label=<i>string</i>;</code></b><br>
|
|
Specify a label for the server section. This can be used to refer to this section
|
|
when using <a href="#pdnsdctl"><code>pdnsd-ctl</code></a>, the pdnsd control utility.<br>
|
|
You can give several server sections the same label, but if you want to change the addresses
|
|
of a server section (see <b><code>ip</code></b> option below) during run-time with
|
|
<code>"pdnsd-ctl server <i>label</i> up <i>dns1</i>,<i>dns2</i>,..."</code>,
|
|
the label must be unique.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ip=<i>string</i>;</code></b><br>
|
|
Give the IP (the address, <em>not</em> the host name) of the server.<br>
|
|
Multiple IP addresses can be given per server section.
|
|
This can be done by entering multiple lines of the form <code>ip=<i>string</i>;</code>
|
|
or a single line like this:
|
|
<p class="indented"><code>ip=<i>string</i>,<i>string</i>,<i>string</i>;</code></p>
|
|
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 <a href="#pdnsdctl"><code>pdnsd-ctl</code></a>,
|
|
the pdnsd control utility.<br>
|
|
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 <code>-6</code> or set <code>run_ipv4=off</code>
|
|
first (see <a href="#runipv4"><code>global</code></a> section) in order to ensure
|
|
that IPv6 addresses are parsed correctly.<br>
|
|
If pdnsd is running in IPv6 mode and you specify an IPv4 address here,
|
|
it will automatically be mapped to an IPv6 address.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="resolvfile">file=<i>string</i>;</a></code></b><br>
|
|
<em>New in version 1.2:</em> This option allows you to give the name of a <code>resolv.conf</code>-style file.
|
|
Of the lines beginning with the <code>nameserver</code> keyword, the second field will be parsed as an
|
|
IP address, as if it were specified with the <code>ip=</code> 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 <a href="#pdnsdctl"><code>pdnsd-ctl</code></a>, the pdnsd control utility.
|
|
This is usually most conveniently done by placing the command <code>"pdnsd-ctl config"</code> in a script
|
|
that is automatically run whenever the DNS configuration changes.<br>
|
|
For example, suppose you have a ppp client that writes the DNS configuration for your ISP to the file
|
|
<code>/etc/ppp/resolv.conf</code> and runs the script <code>/etc/ppp/ip-up</code> when a new
|
|
connection is established. One way of ensuring that pdnsd is automatically reconfigured is to
|
|
add a <code>server</code> section in the config file with <code>file=/etc/ppp/resolv.conf</code> and to
|
|
add the command <code>"pdnsd-ctl config"</code> to <code>/etc/ppp/ip-up</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>port=<i>number</i>;</code></b><br>
|
|
Give the port the remote name server listens on. Default is 53 (the official
|
|
dns port)
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>uptest=(ping|none|if|dev|diald|exec|query);</code></b><br>
|
|
Determine the method to check whether the server is available. Currently
|
|
defined methods are:
|
|
|
|
<ul>
|
|
<li><b><code>ping</code></b>: 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.
|
|
<li><b><code>none</code></b>: The availability status is not changed, only the time stamp is updated.
|
|
<li><b><code>if</code></b>: Check whether the interface (specified in the <code>interface=</code> 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 <code>/dev/isdninfo</code> device file (major#45, minor#255), or the
|
|
isdn uptest will always fail.
|
|
<li><b><code>dev</code></b> and <b><code>diald</code></b>: Perform an <code>if</code> 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 <code>if</code>
|
|
uptest, e.g. <code>"ppp0"</code>) and a device relative to <code>/dev</code> (e.g.
|
|
<code>"modem"</code> for <code>/dev/modem</code> specified using the <code>device=</code> option.
|
|
pdnsd will then look for a pid file for the given interface in <code>/var/lock</code> (e.g.
|
|
<code>/var/run/ppp0.pid</code>) and for a lockfile for the given device (e.g. <code>/var/lock/LCK..modem</code>),
|
|
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 <code>if</code> uptest is executed for the given interface.<br>
|
|
The <code>dev</code> option is for pppd dial-on-demand, <code>diald</code> is the same for diald users.
|
|
<li><b><code>exec</code></b>: Executes a given command in the <code>/bin/sh</code> shell
|
|
(as <code>/bin/sh -c <command></code>)
|
|
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
|
|
<code>uptest_sh</code>. The command is given with the <code>uptest_cmd</code> option (see below).
|
|
For secuity issues, also see that entry.
|
|
<li><b><code>query</code></b>: <em>New in version 1.2:</em>
|
|
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 <code><a href="#querytestname">query_test_name</a></code> option (see below).
|
|
In many cases this test will be a more reliable indicator of availability
|
|
than the ones mentioned before.
|
|
</ul>
|
|
<p>
|
|
The default value is <b><code>none</code></b>.
|
|
<br><br>
|
|
<b>NOTE</b>: If you use on-demand dialing, use <code>none</code>, <code>if</code>,
|
|
<code>dev</code>, <code>diald</code> or <code>exec</code>,
|
|
since <code>ping</code> or <code>query</code> will send packets
|
|
in the specified interval and the interface will thus frequently dial!
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ping_timeout=<i>number</i>;</code></b><br>
|
|
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).<br>
|
|
The default is 600 (one minute).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ping_ip=<i>string</i>;</code></b><br>
|
|
The IP address for the ping test. The default is the IP of the name server.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="querytestname">query_test_name=<i>string</i>;</a></code></b><br>
|
|
<em>New in version 1.2.9:</em>
|
|
Sets the name to be queried when using <code>uptest=query</code> availability test.
|
|
If the string is the unquoted constant <code>none</code>,
|
|
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.<br>
|
|
If the the remote server ignores empty queries, you will probably want to set
|
|
<code>query_test_name="."</code> (the root domain).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>uptest_cmd=<i>string</i>,<i>string</i>;</code></b><br>
|
|
or<br>
|
|
<b><code>uptest_cmd=<i>string</i>;</code></b><br>
|
|
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.<br>
|
|
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.<br>
|
|
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).<br>
|
|
<b>Note that this is not always possible, and that pdnsd should never
|
|
be installed as setuid or setgid.</b>
|
|
The command is executed using <code>/bin/sh</code>, so you should be able to use
|
|
shell builtin commands.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>interval=(<i>timespec</i>|onquery|ontimeout);</code></b><br>
|
|
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.<br>
|
|
If you specify <code>onquery</code> 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 ;-) <br>
|
|
Note that using uptest=exec, you might run into performance problems
|
|
on slow machines when you use that option.
|
|
DON'T use <code>onquery</code> with <code>uptest=ping</code> or
|
|
<code>uptest=query</code>, as it may cause delays if the server does not answer
|
|
(btw, it doesn't make sense anyway).
|
|
Note also that using <code>onquery</code> 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.<br>
|
|
<em>New in version 1.2.3:</em>
|
|
A third possibility is to specify <code>interval=ontimeout</code>.
|
|
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
|
|
<code><a href="#pdnsdctl">pdnsd-ctl</a> config</code> or <code>server</code> command.
|
|
The idea behind this option is to minimize uptests by assuming all
|
|
servers are available until there is reason to believe otherwise.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>interface=<i>string</i>;</code></b><br>
|
|
The network interface (or network device, e.g. <code>"eth0"</code>) for the <code>uptest=if</code> option.
|
|
Must be specified if <code>uptest=if</code> is given.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>device=<i>string</i>;</code></b><br>
|
|
The (modem-) device that is used for the <code>dev</code> uptest. If you use this for a dial-on-demand
|
|
ppp uptest (together with <code>uptest=dev</code>), you need to enter the device you are using for your
|
|
pppd here, e.g. <code>modem</code> for <code>/dev/modem</code>.<br>
|
|
Must be specified if <code>uptest=dev</code> is given.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>timeout=<i>timespec</i>;</code></b><br>
|
|
Set the timeout for the dns query. The default is 120 seconds. You probably want to set this lower.<br>
|
|
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.<br>
|
|
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 <a href="#globaltimeout"><code>global</code></a>
|
|
section for what that means.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>purge_cache=(on|off);</code></b><br>
|
|
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 <code>purge_cache</code> is set to <code>off</code>, 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).<br>
|
|
Default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>caching=(on|off);</code></b><br>
|
|
Specifies if caching shall be performed for this server at all. Default is
|
|
<code>on</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>lean_query=(on|off);</code></b><br>
|
|
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.<br>
|
|
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.<br>
|
|
A last note: If you use multiple pdnsd's that access each other, turning
|
|
this option on is probably a big win.<br>
|
|
This on by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="ednsquery">edns_query=(on|off);</a></code></b><br>
|
|
<em>New in version 1.2.9:</em>
|
|
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.<br>
|
|
The default is <code>off</code>, but if your network can handle UDP payloads
|
|
significantly larger than 512 bytes, the recommended value is <code>on</code>.<br>
|
|
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.
|
|
<br>
|
|
See also the <code><a href="#udpbufsize">udpbufsize</a></code> option above.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>scheme=<i>string</i>;</code></b><br>
|
|
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 <code>scheme_file</code> option on the <code>global</code>
|
|
section to make this option work.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>preset=(on|off);</code></b><br>
|
|
This allows you to specify the initial state of a server before any uptest is performed.
|
|
<code>on</code> specifies that the server is regarded available. The default is <code>on</code>.
|
|
This is especially useful when you set <code>uptest=none;</code> and want to change
|
|
the status of a server only via pdnsd-ctl.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="proxyonly">proxy_only=(on|off);</a></code></b><br>
|
|
When this option is set to <code>on</code>, 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).<br>
|
|
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).<br>
|
|
I recommend that you turn on <code>lean_query</code> when using this option.<br>
|
|
Default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code><a name="rootserver">root_server=(on|off|discover);</a></code></b><br>
|
|
Set this option to <code>on</code> 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 <code>root_server=on</code> 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
|
|
<code>"dig . ns"</code>.<br>
|
|
This option is also necessary if you use the <a href="#delegationonly"><code>delegation_only</code></a> option.<br>
|
|
<em>New in version 1.2.8:</em> This option may also be set to "<code>discover</code>".
|
|
This will cause pdnsd to query the servers provided with the <code>ip=</code> option
|
|
to obtain the full list of root servers. The root-server addresses will replace the addresses
|
|
specified with the <code>ip=</code> option.
|
|
This will only be done once on startup, or after a "<code>pdnsd-ctl config</code>" command.
|
|
In this case the name servers specified with the <code>ip=</code> 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 <code>root_server=on</code>
|
|
had been specified.<br>
|
|
Default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>randomize_servers=(on|off);</code></b><br>
|
|
<em>New in version 1.2.6:</em> Set this option to <code>on</code> 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.<br> The default is off, but if you are resolving from root servers setting this
|
|
option on is highly recommended. If <code>root_server=on</code> this option also effects
|
|
the query order of the name servers for the top-level domains.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>reject=<i>string</i>;</code></b><br>
|
|
<em>New in version 1.2.6:</em> 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.<br>
|
|
Multiple addresses or address/mask pairs may be specified; this can be done by entering
|
|
multiple lines of the form <code>reject=<i>string</i>;</code>
|
|
or a single line like this:
|
|
<p class="indented"><code>reject=<i>string</i>,<i>string</i>,<i>string</i>;</code></p>
|
|
How pdnsd reacts when an address in the reply matches one in the <code>reject</code> list,
|
|
depends on the <code>reject_policy</code> option, see below.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>reject_policy=(fail|negate);</code></b><br>
|
|
<em>New in version 1.2.6:</em>
|
|
This option determines what pdnsd does when an address in the reply from a name server
|
|
matches the <code>reject</code> list (see above). If this option is set to
|
|
<code>fail</code>, pdnsd will try another server, or, if there no more servers to try,
|
|
return the answer SERVFAIL. If this option is set to <code>negate</code>, pdnsd will
|
|
immediately return the answer NXDOMAIN (unknown domain) without querying additional
|
|
servers. The <code>fail</code> setting is useful if you don't always trust the servers in
|
|
this section, but do trust the servers in the following section. The <code>negate</code>
|
|
setting can be used to completely censor certain IP addresses. In this case you should put
|
|
the same <code>reject</code> list in every server section, and also set the
|
|
<code>reject_recursively</code> option (see below) to true.<br>
|
|
The default is <code>fail</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>reject_recursively=(on|off);</code></b><br>
|
|
<em>New in version 1.2.6:</em> Normally pdnsd checks for addresses in the
|
|
<code>reject</code> list (see above) only when the reply comes directly from a name server
|
|
listed in the configuration file. With this option set to <code>on</code>, 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).<br>
|
|
Default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>policy=(included|excluded|simple_only|fqdn_only);</code></b><br>
|
|
pdnsd supports inclusion/exclusion lists for server sections: with <code>include=</code>
|
|
and <code>exclude=</code> (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 <code>policy=</code> option determines whether this server is used for the
|
|
lookup for that domain name; when <code>included</code> is given, the server will
|
|
be asked, and when <code>excluded</code> is given, it will not.
|
|
If <code>simple_only</code> is given the server will be used if the name to lookup
|
|
is a simple (single-label) domain name, on the other hand if <code>fqdn_only</code>
|
|
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).<br>
|
|
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 <code>resolv.conf</code>).
|
|
This may be of use sometimes.<br>
|
|
<em>Note</em>: the <code>simple_only</code> and <code>fqdn_only</code> 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.
|
|
<code>fqdn_only</code> 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 <code>simple_only</code> and
|
|
<code>fqdn_only</code> are good for, you are probably better off not using them.<br>
|
|
The default for this option is <code>included</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>include=<i>string</i>;</code></b><br>
|
|
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 <code>policy</code>).<br>
|
|
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. <code>".foo.bar."</code>
|
|
will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.<br>
|
|
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:
|
|
<code>exclude="foo.bar."; include=".foo.bar.";</code><br>
|
|
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.<br>
|
|
pdnsd now also accepts a more compact notation for adding several <code>"include"</code> entries in
|
|
one line, e.g.:
|
|
<p class="indented"><code>include=".foo",".bar",".my.dom";</code></p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>exclude=<i>string</i>;</code></b><br>
|
|
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 <code>policy</code>).<br>
|
|
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. <code>".foo.bar."</code>
|
|
will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.<br>
|
|
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:
|
|
<code>include="foo.bar."; exclude=".foo.bar.";</code><br>
|
|
pdnsd now also accepts a more compact notation for adding several <code>"exclude"</code> entries in
|
|
one line, e.g.:
|
|
<p class="indented"><code>exclude=".foo",".bar",".my.dom";</code></p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3>2.1.3 <a name="rrsection"><code>rr</code> Section</a></h3>
|
|
Every <code>rr</code> 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.<br>
|
|
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 <b>NOT</b> intended and not capable to work as a full-featured name server.
|
|
<br><br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>name=<i>string</i>;</code></b><br>
|
|
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 <code>a</code>, <code>ptr</code>, <code>cname</code>,
|
|
<code>mx</code>, <code>ns</code> or <code>soa</code> 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.).<br>
|
|
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.<br>
|
|
<em>New in version 1.2:</em> 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 *.<br>
|
|
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.<br>
|
|
Before you can specify an <code>rr</code> section with <code>name=*.mydomain</code>
|
|
you must define some records for mydomain, typically NS and/or SOA records.
|
|
Example:
|
|
<pre>
|
|
rr {
|
|
name = mydomain;
|
|
ns = localhost;
|
|
soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
|
|
}
|
|
rr {
|
|
name = *.mydomain;
|
|
a = 192.168.1.10;
|
|
}</pre>
|
|
In this example, www.mydomain and ftp.mydomain will resolve to the numeric
|
|
address 192.168.1.10 (unless you add <code>rr</code> 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 <code>rr</code> section.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ttl=<i>timespec</i>;</code></b><br>
|
|
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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>authrec=(on|off);</code></b><br>
|
|
If this is turned on, pdnsd will create authoritative local records for this <code>rr</code> 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.<br>
|
|
This is on by default.<br>
|
|
Please note that this only has an effect if it precedes the <code>name</code> option!
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>reverse=(on|off);</code></b><br>
|
|
<em>New in version 1.2:</em> 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.<br>
|
|
The default is <code>off</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>a=<i>string</i>;</code></b><br>
|
|
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 <code>name</code> option.<br>
|
|
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.<br>
|
|
This option be may used multiple times within an <code>rr</code> section, causing
|
|
multiple addresses to be defined for the name. However, if you put the different addresses
|
|
in different <code>rr</code> sections for the same name, the definition in the last
|
|
<code>rr</code> section will cancel the definitions in the previous ones.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ptr=<i>string</i>;</code></b><br>
|
|
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:<br>
|
|
<pre>
|
|
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;
|
|
}</pre>
|
|
The second section is for reverse resolving and uses the <code>ptr</code> option.
|
|
Note that you can get the same effect by specifying only the first <code>rr</code> section
|
|
with <code>reverse=on</code>.<br>
|
|
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
|
|
(<code>1.0.0.127</code> instead of <code>127.0.0.1</code>) where each byte of the adress written
|
|
as number constitutes a sub-domain under the domain <code>in-addr.arpa.</code> <br>
|
|
So, if you want to compose an adress for reverse resolving, take your ip in dotted notation (e.g. <code>1.2.3.4</code>),
|
|
reverse the byte order (<code>4.3.2.1</code>) and append in-addr.arpa. (<code>4.3.2.1.in-addr.arpa.</code>)
|
|
Then, define an <code>rr</code> section giving this address as <code>name</code> and the domain name corresponding to
|
|
that ip in the <code>ptr</code> option.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>cname=<i>string</i>;</code></b><br>
|
|
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.<br>
|
|
A useful application for CNAMEs is giving short, easy to remember nicknames to hosts with complicated names.
|
|
For example, you might want the name "<tt>news</tt>" to refer to your ISP's news server "<tt>nntp2.myisp.com</tt>".
|
|
Instead of adding an A record for "<tt>news</tt>" with the same address as "<tt>nntp2.myisp.com</tt>", you could
|
|
put in a CNAME pointing to "<tt>nntp2.myisp.com</tt>", so that if the IP address of the news server changes,
|
|
there is no need to update the record for "<tt>news</tt>".<br>
|
|
To implement this with pdnsd, you could add the following section to your configuration file:<br>
|
|
<pre>
|
|
rr {
|
|
name = news;
|
|
cname = nntp2.myisp.com;
|
|
owner = localhost;
|
|
}</pre>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>mx=<i>string</i>,<i>number</i>;</code></b><br>
|
|
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.<br>
|
|
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 <tt>joe@example.com</tt>, it would look for the MX record for <tt>example.com</tt> and find
|
|
that the name of mail server for that domain is, say, <tt>mail.example.com</tt>.
|
|
The SMTP server then gets the A record for <tt>mail.example.com</tt>, and connects to the mail server.<br>
|
|
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).<br>
|
|
Don't define MX records with pdnsd unless you know what you're doing.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>owner=<i>string</i>;</code></b><br>
|
|
or<br>
|
|
<b><code>ns=<i>string</i>;</code></b><br>
|
|
Defines an NS (name server) record. Specifies the name of the host which should be authoritative for the records
|
|
you defined in the <code>rr</code> section. This is typically the host pdnsd runs on.<br>
|
|
<em>Note:</em> In previous versions of pdnsd this option had to be specified before
|
|
any <code>a</code>, <code>ptr</code>, <code>cname</code>, <code>mx</code> or <code>soa</code> entries.
|
|
In version 1.2, the restrictions on this option are same as the options just mentioned,
|
|
and it must listed after the <code>name=</code> option.
|
|
This can be a pain if you want to use an old config file which specifies <code>owner=</code>
|
|
before <code>name=</code> (sorry about that).
|
|
Apart from greater consistency, the advantage is that you can now specify as many NS records as you like (including zero).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>soa=<i>string</i>,<i>string</i>,<i>number</i>,<i>timespec</i>,<i>timespec</i>,<i>timespec</i>,<i>timespec</i>;</code></b><br>
|
|
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. <br>
|
|
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.<br>
|
|
The 4th parameter is the refresh timeout. It specifies after what amount
|
|
of time a caching server should attempt to refresh the cached record.<br>
|
|
The 5th parameter specifies a time after which a caching server should attempt
|
|
to refresh the record after a refresh failure.<br>
|
|
The 6th parameter defines the timeout after which a cached record expires if it
|
|
has not been refreshed.<br>
|
|
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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>txt=<i>string</i>,...,<i>string</i>;</code></b><br>
|
|
<em>New in version 1.2.9:</em>
|
|
Defines an TXT record. You can specify one or more strings here.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3>2.1.4 <a name="negsection"><code>neg</code> Section</a></h3>
|
|
Every <code>neg</code> 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 <code>neg</code> sections remain
|
|
valid until they are explicitely invalidated or deleted by the user using
|
|
<a href="#pdnsdctl"><code>pdnsd-ctl</code></a>.<br>
|
|
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<br>
|
|
<pre>
|
|
neg {
|
|
name = news;
|
|
types = domain;
|
|
}
|
|
neg {
|
|
name = mail;
|
|
types = domain;
|
|
}</pre>
|
|
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!<br>
|
|
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<br>
|
|
<code>neg {name=example.com; types=domain;}</code> in the
|
|
config file, this will also negate www.example.com, xxx.adserver.example.com, etc.
|
|
<br><br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>name=<i>string</i>;</code></b><br>
|
|
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.).<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ttl=<i>timespec</i>;</code></b><br>
|
|
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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>types=(domain|<i>rr_type</i>[,<i>rr_type</i>[,<i>rr_type</i>[,...]]]);</code></b><br>
|
|
Specifies what is to be cached negatively: <code>domain</code> 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
|
|
<code>domain</code> and the RR types are mutually exclusive.<br>
|
|
The RR types are specified using their official names from the RFC's in capitals,
|
|
e.g. <code>A</code>, <code>CNAME</code>, <code>NS</code>, <code>PTR</code>, <code>MX</code>,
|
|
<code>AAAA</code>, ...<br>
|
|
The command <code>pdnsd-ctl list-rrtypes</code> will give you a complete list
|
|
of those types. <a href="#pdnsdctl"><code>pdnsd-ctl</code></a> is built along with pdnsd
|
|
and will be installed in the same directory as the pdnsd binary during <code>make install</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3>2.1.5 <a name="sourcesection"><code>source</code> Section</a></h3>
|
|
Every source section allows you to let pdnsd read the records from a file in an
|
|
<code>/etc/hosts</code>-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 <code>/etc/hosts</code>.<br>
|
|
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.<br>
|
|
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
|
|
<code>/etc/hosts</code>, it may contain information not needed by pdnsd).
|
|
<br><br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>owner=<i>string</i>;</code></b><br>
|
|
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.<br>
|
|
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.).<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>ttl=<i>timespec</i>;</code></b><br>
|
|
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).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>file=<i>string</i>;</code></b><br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>serve_aliases=(on|off);</code></b><br>
|
|
If this is turned on pdnsd will serve the aliases given in a <code>hosts</code>-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.<br>
|
|
This feature was suggested by Bert Frederiks.<br>
|
|
It is off by default.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<b><code>authrec=(on|off);</code></b><br>
|
|
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 <code>file</code> options
|
|
subsequent to this option.<br>
|
|
This is on by default.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h3>2.1.6 <a name="includesection"><code>include</code> Section</a></h3>
|
|
A configuration file may include other configuration files.
|
|
However, only the top-level configuration file may contain <a href="#globalsection"><code>global</code></a>
|
|
and <a href="#serversection"><code>server</code></a> sections,
|
|
thus include files are effectively limited to sections that add local definitions to the cache.<br>
|
|
Include sections currently only have one type of option, which may be given multiple times within a single section.
|
|
<br><br>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td>
|
|
<b><code>file=<i>string</i>;</code></b><br>
|
|
The string specifies a file name. For every <code>file</code> 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.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<h2>3 <a name="pdnsdctl">pdnsd-ctl</a></h2>
|
|
<p>
|
|
pdnsd-ctl allows you to configure pdnsd at run time. To make this work, you have to start pdnsd with the <code>-s</code>
|
|
option (or use the <code><a href="#statusctl">status_ctl</a></code> option in the config file). You also should make sure that you
|
|
have appropriate permissions on the control socket (use the <code>ctl_perms</code> 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!</p>
|
|
<p>
|
|
pdnsd-ctl accepts two command-line options starting with a dash.<br>
|
|
<code>-c</code> 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!<br>
|
|
<code>-q</code> can be used to make the output of pdnsd-ctl less verbose.</p>
|
|
<p>
|
|
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.<br>
|
|
In the following table, keywords are in a normal font, while placeholders are in italics.<br>
|
|
Alternatives are specified like (alt1|alt2|alt3).
|
|
Optional arguments are placed between square brackets [].</p>
|
|
<table width="100%" bgcolor="#CCCCCC" cellpadding=10>
|
|
<tr>
|
|
<td><b>Command</b></td>
|
|
<td><b>Arguments</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">help</td>
|
|
<td></td>
|
|
<td>Print a command summary.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap">version</td>
|
|
<td></td>
|
|
<td>Print version and license info.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>status</td>
|
|
<td></td>
|
|
<td>
|
|
Print a description of pdnsd's cache status, thread status and configuration.
|
|
Also shows which remote name servers are assumed to be available.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>server</td>
|
|
<td valign=top>(<i>index</i>|<i>label</i>) (up|down|retest) [<i>dns1</i>[,<i>dns2</i>[,...]]]</td>
|
|
<td>
|
|
Set the status of the server with the given <i>index</i> or <i>label</i> (where the given label
|
|
matches the one given with the 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
|
|
<code>pdnsd.conf</code> starting with 0. Use the status command to view the indices and labels.
|
|
You can specify <code>all</code> instead of an index or label to perform the action for all
|
|
servers registered with pdnsd. Example:<br>
|
|
<code>pdnsd-ctl server 0 retest</code><br>
|
|
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 <code>/etc/ppp/ip-up</code> script called by <code>pppd</code> you could
|
|
place the following line:<br>
|
|
<code>pdnsd-ctl server isplabel up $DNS1,$DNS2</code><br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>record</td>
|
|
<td valign=top><i>name</i> (delete|invalidate)</td>
|
|
<td>
|
|
Delete or invalidate the records of the given domain <i>name</i> 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).<br>
|
|
For local records (i.e., records that were given in the config file
|
|
using a <code>rr</code> section, records read from a hosts-style file
|
|
and records added using pdnsd-ctl), invalidation has no effect. Deletion
|
|
will work, though. Example:<br>
|
|
<code>pdnsd-ctl record localhost. delete</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>source</td>
|
|
<td valign=top><i>fn</i> <i>owner</i> [<i>ttl</i>] [(on|off)] [noauth]</td>
|
|
<td>
|
|
Load a hosts-style file. Works like using the pdnsd
|
|
<a href="#sourcesection">source configuration section</a>.
|
|
<i>owner</i> and <i>ttl</i> are used as in the source section. <i>ttl</i> 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).
|
|
<code>noauth</code> is used to make the domains non-authoritative - please see
|
|
the description of the <code>authrec</code> config file options for a description of what
|
|
that means.
|
|
<i>fn</i> is the filename. The file must be readable by pdnsd! Example:<br>
|
|
<code>pdnsd-ctl source /etc/hosts localhost. 900 off</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>a <i>addr</i> <i>name</i> [<i>ttl</i>] [noauth]</td>
|
|
<td rowspan=6>
|
|
Add a record of the given type to the pdnsd cache, replacing existing
|
|
records for the same <i>name</i> and type. The 2nd argument corresponds
|
|
to the value of the option in the 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 address-to-hostname
|
|
mapping. See the documentation for the <code>rr</code> section for more details.
|
|
In case of A and AAAA records, the <i>addr</i> argument may be a list of IP addresses,
|
|
separated by commas or white space, causing multiple addresses to be defined
|
|
for the same <i>name</i>.
|
|
The <i>ttl</i> is optional, the default is 900 seconds.
|
|
<code>noauth</code> is used to make the domains non-authoritative - please see
|
|
the description of the <code>authrec</code> config file options for a description of what
|
|
that means.
|
|
If you want no other record than the newly added in the cache, do<br>
|
|
<code>pdnsd-ctl record <i>name</i> delete</code>
|
|
before adding records. This is also better when overwriting local records. Example:<br>
|
|
<code>pdnsd-ctl add a 127.0.0.1 localhost. 900</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>aaaa <i>addr</i> <i>name</i> [<i>ttl</i>] [noauth]</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>ptr <i>host</i> <i>name</i> [<i>ttl</i>] [noauth]</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>cname <i>host</i> <i>name</i> [<i>ttl</i>] [noauth]</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>mx <i>host</i> <i>name</i> <i>pref</i> [<i>ttl</i>] [noauth]</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>add</td>
|
|
<td valign=top>ns <i>host</i> <i>name</i> [<i>ttl</i>] [noauth]</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>neg</td>
|
|
<td valign=top><i>name</i> [<i>type</i>] [<i>ttl</i>]</td>
|
|
<td>
|
|
Add a negatively cached record to pdnsd's cache, replacing existing
|
|
records for the same <i>name</i> and <i>type</i>. 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 <i>ttl</i> is optional, the default is 900 seconds.<br>
|
|
You can get a list of all types you can pass to this command using
|
|
<code>pdnsd-ctl list-rrtypes</code>. The type is treated case-sensitive!
|
|
Example:<br>
|
|
<code>pdnsd-ctl neg foo.bar A 900</code><br>
|
|
<code>pdnsd-ctl neg foo.baz 900</code><br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>config</td>
|
|
<td valign=top>[<i>filename</i>]</td>
|
|
<td>
|
|
Reload pdnsd's configuration file.<br>
|
|
The config file must be owned by the uid that pdnsd had when it was
|
|
started, and be readable by pdnsd's <a href="#runas"><code>run_as</code></a> uid. If no file name is
|
|
specified, the config file used at start-up is reloaded.<br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>include</td>
|
|
<td valign=top><i>filename</i></td>
|
|
<td>
|
|
Parse the given file as an include file, see the documentation on
|
|
<a href="#includesection">include sections</a> for a description
|
|
what this file may contain.<br>
|
|
This command is useful for adding definitions to the cache without reconfiguring pdnsd.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>eval</td>
|
|
<td valign=top><i>string</i></td>
|
|
<td>
|
|
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, <a href="#globalsection"><code>global</code></a> and
|
|
<a href="#serversection"><code>server</code></a> sections are not allowed,
|
|
just as in <a href="#includesection">include files</a>.
|
|
If multiple strings are given, they will be joined using newline chars
|
|
and parsed together.<br>
|
|
This command is useful for adding records interactively to the cache
|
|
that cannot be defined using the "<code>pdnsd-ctl add</code>" command,
|
|
(e.g. soa records).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>empty-cache</td>
|
|
<td valign=top>[[+|-]<i>name</i> ...]</td>
|
|
<td>
|
|
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 <code>"pdnsd-ctl config"</code> or
|
|
<code>"pdnsd-ctl include <i>filename</i>"</code> immediately afterwards.<br>
|
|
The <code>"pdnsd-ctl empty-cache"</code> 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 <code>"pdnsd-ctl record <i>name</i> delete"</code>,
|
|
this is also much more efficient.<br>
|
|
Examples:<br>
|
|
<code>pdnsd-ctl empty-cache</code><br>
|
|
This command will remove all cache entries.<br>
|
|
<br>
|
|
<code>pdnsd-ctl empty-cache microsoft.com msft.net</code><br>
|
|
This will remove all entries ending in microsoft.com or msft.net.<br>
|
|
<br>
|
|
<code>pdnsd-ctl empty-cache -localdomain -168.192.in-addr.arpa .</code><br>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>dump</td>
|
|
<td valign=top>[<i>name</i>]</td>
|
|
<td>
|
|
Print information stored in the cache about <i>name</i>.
|
|
If <i>name</i> begins with a dot and is not the root domain, information about
|
|
the names in the cache ending in <i>name</i> (including <i>name</i> without
|
|
the leading dot) will be printed.
|
|
If <i>name</i> is not specified, information about all the names in the cache will
|
|
be printed.<br>
|
|
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.<br>
|
|
This command is mainly useful for diagnostic purposes.<br>
|
|
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 <code>more</code> or <code>less</code>),
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="nowrap" valign=top>list-rrtypes</td>
|
|
<td></td>
|
|
<td>
|
|
List available rr types for the neg command.
|
|
Note that those are only used for the neg command, not for add!
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<h2>4 contrib/</h2>
|
|
The contrib directory in the pdnsd distribution contains useful user-contributed scripts.<br>
|
|
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.
|
|
<br>
|
|
<br>
|
|
<h2>5 Problems...</h2>
|
|
If you have problems with configuring or running pdnsd, be sure to read the <a href="faq.html">FAQ</a>.
|
|
If this does not help you, pdnsd crashes or you find bugs, please mail one of the authors.<br>
|
|
<em>Note added by <a href="mailto:p.a.rombouts@home.nl">Paul A. Rombouts</a></em>:
|
|
Thomas Moestl no longer maintains the code. I have revised the code and added new features.
|
|
See <a href="../../README.par"><code>README.par</code></a> and the
|
|
<a href="../../ChangeLog"><code>ChangeLog</code></a> in the source directory
|
|
(or <code>/usr/share/doc/pdnsd-<version></code> 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
|
|
<a href="../../README.par"><code>README.par</code></a>.
|
|
<br>
|
|
<br>
|
|
<h2>6 Hacking</h2>
|
|
Here comes some information you might find useful for hacking pdnsd.
|
|
<br>
|
|
<h3>6.1 Source files</h3>
|
|
<table width="100%" cellspacing=1 cellpadding=7>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">Makefile.am, configure.in, acconfig.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
autoconf/automake/autoheader scripts. Makefile.am's are in most subdirectories.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">pdnsd.spec.in</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
A template from which configure generates a spec file for building rpm's for various
|
|
distributions.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">version</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Contains only the program version string. Needed for several templates.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/rc/*</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
rc (start-up) scripts for various linux distributions.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/cache.c</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
The pdnsd cache subsystem(s) as defined in src/cache.h.
|
|
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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/pdnsd-ctl/*</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Contains the code for pdnsd-ctl, a program that allows you to control pdnsd at run time.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/conf-lex.l.in</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
The lex/flex source file for the config file lexer. This is a template because there might be
|
|
inserted "%option yylineno" for proper flex support.
|
|
<font color="#990000">(obsolete, superseded by src/conf-parser.c)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/conf-lex.l</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
This is automatically generated by configure from conf-lex.l.in. It may be overwritten
|
|
in any make, so never modify this, but conf-lex.l.in instead!
|
|
<font color="#990000">(obsolete, superseded by src/conf-parser.c)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/conf-parse.y</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
The yacc/bison source of the config file parser.
|
|
<font color="#990000">(obsolete, superseded by src/conf-parser.c)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/conf-parser.c, src/conf-parser.h, src/conf-keywords.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
The config file parser written purely in C (versions 1.1.10-par and later).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/conff.c, src/conff.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
The configuration handler functions and their prototypes. The parser is called from here.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/consts.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Some constants used by the parser, config file handler functions and in the server status thread,
|
|
among others.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/dns.c, src/dns.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define dns message structures, constants, and some common dns data handlers. dns.h contains gcc-specific
|
|
code (in praticular, "__attribute__((packed))").
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/dns_answer.c, src/dns_answer.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define functions that answer incoming dns queries.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/dns_query.c, src/dns_query.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define functions to manage outgoing dns queries.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/error.c, src/error.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Functions for error output to stderr or the syslog, and debug output to stderr or <code>pdnsd.debug</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/hash.c, src/hash.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Contains the code for storing and looking up cache entries in the hash table.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/helpers.c, src/helpers.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define miscellaneous helper functions.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/icmp.c, src/icmp.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define a function for performing a ping test. This contains OS-specific code.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/main.c</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Contains main(), which holds the command line parser, performs initialisations and signal handling.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/make_hashconvtable.c</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Contains the code for the executable <code>make_hashconvtable</code>, which is only run once, during build time, to generate the file <code>hashconvtable.h</code>, used by <code>src/hash.c</code> (versions 1.1.10-par and later).
|
|
<font color="#990000">(obsolete since version 1.2)</font>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/make_rr_types_h.pl</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
A perl script for generating src/rr_types.h,
|
|
a C header file containing macro definitions and tables needed for handling the
|
|
RR types known to pdnsd, from the text file src/rr_types.in.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/rr_types.c, src/rr_types.h, src/rr_types.in</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
These define tables and macros needed for handling the RR types known to pdnsd.
|
|
Since version 1.2.9, rr_types.h is an automatically generated file,
|
|
see make_rr_types_h.pl.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/netdev.c, src/netdev.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define functions for network device handling. OS-specific.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/servers.c, src/servers.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define functions for the server status thread that performs the periodical uptests.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td bgcolor="#FFCCFF" width="20%">src/status.c, src/status.h</td>
|
|
<td bgcolor="#CCFFFF" width="80%">
|
|
Define functions for the status control thread. This is pdnsd's interface to pdnsd-ctl.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<hr>
|
|
<address>
|
|
Copyright (C) 2000, 2001 <a href="mailto:tmoestl@gmx.net">Thomas Moestl</a><br>
|
|
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2012 <a href="mailto:p.a.rombouts@home.nl">Paul A. Rombouts</a>
|
|
</address>
|
|
<p>
|
|
<i>Last revised: 19 April 2012 by Paul A. Rombouts</i>
|
|
</p>
|
|
</body>
|
|
</html>
|