-->
PDNSD.CONF(5) PDNSD.CONF(5)
NAME
pdnsd.conf - The configuration file for pdnsd
DESCRIPTION
This manual page describes the layout of the pdnsd(8) configuration
file and the available configuration options. The default location of
the file is /etc/pdnsd.conf. This may be changed with the -c command
line option. An example pdnsd.conf comes with the pdnsd distribution
in the documentation directory or in /etc/pdnsd.conf.sample.
FILE FORMAT
The configuration file is divided into sections. Each section is pre‐
fixed with the section name and opening curlies ({) and closed with
closing curlies (}). In each section, configuration options can be
given in the form
option_name=option_value;
Option value may be a string literal, a number, a time specification or
a constant. In previous versions of pdnsd strings had to be enclosed
in quotes ("), but since version 1.1.10 this is no longer necessary,
unless a string contains a special character such as whitespace, a
token that normally starts a comment, or one of ",;{}".
A time specification consists a sequence of digits followed by a one-
letter suffix. The following suffixes are recognized: s (seconds), m
(minutes), h (hours), d (days) and w (weeks). If the suffix is miss‐
ing, seconds are assumed. If several time specifications are concate‐
nated, their values are added together; e.g. 2h30m is interpreted as
2*60*60 + 30*60 = 9000 seconds.
Some options take more than one value; in this case, the values are
separated with commas.
If you may supply one of a set of possible values to an option, this is
noted in the documentation as (option1|option2|option3|...)
The constants true|false and yes|no are accepted as synonyms for the
constants on|off.
Comments may be enclosed in /* and */, nested comments are possible. If
the # sign or two slashes (//) appear in the configuration file, every‐
thing from these signs to the end of the current line is regarded as a
comment and ignored.
There are examples for nearly all options in the sample config file.
global Section
The global section specifies parameters that affect the overall
behaviour of the server. If you specify multiple global sections, the
settings of those later in the file will overwrite the earlier given
values.
These are the possible options:
perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB.
If the disk cache is switched off, 8 bytes will still be written
to disk. The memory cache is always 10kB larger than the file
cache. This value is 2048 (2 MB) by default.
cache_dir=string;
Set the directory you want to keep the cache in. The default is
"/var/cache/pdnsd" (unless pdnsd was compiled with a different
default).
server_port=number;
Set the server port. This is especially useful when you want to
start the server and are not root. Note that you may also not
specify uptest=ping in the server section as non-root.
The default port is 53, the RFC-standard one. Note that you
should only use non-standard ports when you only need clients on
your machine to communicate with the server; others will proba‐
bly fail if the try to contact the server on the basis of an NS
record, since the A record that supplies the address for (among
others) name servers does not have a port number specification.
server_ip=string;
or
interface=string;
Set the IP address pdnsd listens on for requests. This can be
useful when the host has several interfaces and you want pdnsd
not to listen on all interfaces. For example, it is possible to
bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a for‐
warder for BIND. The default setting for this option is
server_ip=any, which means that pdnsd will listen on all of your
local interfaces. Presently you can only specify one address
here; if you want pdnsd to listen on multiple interfaces but not
all you will have to specify server_ip=any and use firewall
rules to restrict access.
The IP address used to need quotation marks around it, but since
version 1.1.10 this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and
you want to specify an IPv6 address here, then unless pdnsd was
compiled to start up in IPv6 mode by default, you will need to
use the -6 command-line option or set run_ipv4=off first (see
below) in order to ensure that the IPv6 address is parsed cor‐
rectly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address
here, it will automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface
such as "lo" or "eth0" here, instead of an IP address (this has
been tested on Linux, and may or may not work on other plat‐
forms). 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.
linkdown_kluge=(on|off);
This option enables a kluge that some people might need: when
all servers are marked down, with this option set the cache is
not even used when a query is received, and a DNS error is
returned in any case. The only exception from this is that local
records (as specified in rr and source sections are still served
normally. In general, you probably want to get cached entries
even when the network is down, so this defaults to off.
max_ttl=timespec;
This option sets the maximum time a record is held in cache. All
dns resource records have a time to live field that says for
what period of time the record may be cached before it needs to
be requeried. If this is more than the value given with max_ttl,
this time to live value is set to max_ttl. This is done to pre‐
vent records from being cached an inappropriate long period of
time, because that is almost never a good thing to do. Default
is 604800s (one week).
min_ttl=timespec;
This option sets the minimum time a record is held in cache. All
dns resource records have a time to live field that says for
what period of time the record may be cached before it needs to
be requeried. If this is less than the value given with min_ttl,
this time to live value is set to min_ttl. Default is 120 sec‐
onds.
neg_ttl=timespec;
This option sets the time that negatively cached records will
remain valid in the cache if no time to live can be determined.
This is always the case when whole domains are being cached neg‐
atively, and additionally when record types are cached nega‐
tively for a domain for which no SOA record is known to pdnsd.
If a SOA is present, the ttl of the SOA is taken.
neg_rrs_pol=(on|off|auth);
This sets the RR set policy for negative caching; this tells
pdnsd under which circumstances it should cache a record type
negatively for a certain domain. off will turn the negative
caching of record types off, on will always add a negative cache
entry when a name server did not return a record type we asked
it for, and auth will only add such entries if the answer came
from an authoritative name server for that domain. The preset is
auth. This is normally the right thing, as some caching servers
behave strangely.
neg_domain_pol=(on|off|auth);
This is analogue to neg_rrs_pol for whole domain negative
caching. It should be safe to set this on, because I have not
seen a caching server that will falsely claim that a domain does
not exist.
The default is auth.
run_as=string;
This option allows you to let pdnsd change its user and group id
after operations that needed privileges have been done. This
helps minimize security risks and is therefore recommended. The
supplied string gives a user name whose user id and primary
group id are taken.
A little more details: after reading the config file, becoming a
daemon (if specified) and starting the server status thread, the
main thread changes its gid and uid, as do all newly created
threads thereafter. By taking another uid and gid, those threads
run with the privileges of the specified user. Under Linux and
FreeBSD, the server status thread runs with the original privi‐
leges only when the strict_setuid option is set to off (see
below, on by default), because these may be needed for exec
uptests. The manager thread also retains its original privileges
in this case. You should take care that the user you specify
has write permissions on your cache file and status pipe (if you
need a status pipe). You should look out for error messages like
"permission denied" and "operation not permitted" to discover
permission problems.
strict_setuid=(on|off);
When used together with the run_as option, this option lets you
specify that all threads of the program will run with the privi‐
leges of the run_as user. This provides higher security than the
normal run_as option, but is not always possible. See the run_as
option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(on|off);
Normally, pdnsd queries all servers in recursive mode (i.e.
instructs servers to query other servers themselves if possible,
and to give back answers for domains that may not be in its
authority), and accepts additional records with information for
servers that are not in the authority of the queried server.
This opens the possibility of so-called cache poisoning: a mali‐
cious attacker might set up a dns server that, when queried,
returns forged additional records. This way, he might replace
trusted servers with his own ones by making your dns server
return bad IP addresses. This option protects you from cache
poisoning by rejecting additional records that do not describe
domains in the queried servers authority space and not doing
recursive queries any more. An exception to this rule are the
servers you specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular,
more queries might be necessary for the same operation.
You should also notice that there may be other similar security
problems, which are essentially problems of the DNS, i.e. any
"traditional" server has them (the DNS security extensions solve
these problems, but are not widely supported). One of this vul‐
nerabilities is that an attacker may bombard you with forged
answers in hopes that one may match a query you have done. If
you have done such a query, one in 65536 forged packets will be
succesful (i.e. an average packet count of 32768 is needed for
that attack). pdnsd can use TCP for queries, which has a
slightly higher overhead, but is much less vulnerable to such
attacks on sane operating systems. Also, pdnsd chooses random
query ids, so that an attacker cannot take a shortcut. If the
attacker is able to listen to your network traffic, this attack
is relatively easy, though.
This vulnerability is not pdnsd’s fault, and is possible using
any conventional name server (pdnsd is perhaps a little more
secured against this type of attacks if you make it use TCP).
The paranoid option is off by default.
scheme_file=string;
In addition to normal uptests, you may specify that some servers
shall only be queried when a certain pcmcia-cs scheme is active
(only under linux). For that, pdnsd needs to know where the file
resides that holds the pcmcia scheme information. Normally, this
is either /var/lib/pcmcia/scheme or /var/state/pcmcia/scheme.
status_ctl=(on|off);
This has the same effect as the -s command line option: the sta‐
tus control is enabled when on is specified.
Added by Paul Rombouts: Note that pdnsd-ctl allows run-time con‐
figuration of pdnsd, even the IP addesses of the name servers
can be changed. If you’re not using pdnsd-ctl and you want maxi‐
mum security, you should not enable this option. It is disabled
by default.
daemon=(on|off);
This has the same effect as the -d command line option: the dae‐
mon mode is enabled when on is specified.
Default is off.
tcp_server=(on|off);
tcp_server=on has the same effect as the -t or --tcp command-
line option: it enables TCP serving. Similarly, tcp_server=off
is like the --notcp command-line option.
Default is on.
pid_file=string;
This has the same effect as the -p command line option: you can
specify a file that pdnsd will write its pid into when it starts
in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can
set the verbosity of pdnsd’s messages with it. The argument is a
number between 0 (few messages) to 3 (most messages).
query_method=(tcp_only|udp_only|tcp_udp);
This has the same effect as the -m command line option. Read the
documentation for the command line option on this. tcp_only cor‐
responds to the to, udp_only to the uo and tcp_udp to the tu
argument of the command line option.
If you use query_method=tcp_udp, it is recommended that you also
set the global timeout option to at least twice the longest
server timeout.
run_ipv4=(on|off);
This has the same effect as the -4 or -6 command line option: if
on is specified, IPv4 support is enabled, and IPv6 support is
disabled (if available). If off is specified, IPv4 will be dis‐
abled and IPv6 will be enabled. For this option to be
meaningful, pdnsd needs to be compiled with support for the pro‐
tocol you choose. If pdnsd was compiled with both IPv4 and IPv6
support, and you want to include IPv6 addresses in the configu‐
ration file, you will probably need to specify run_ipv4=off
first to ensure that the IPv6 addresses are parsed correctly.
debug=(on|off);
This has the same effect as the -g command line option: the
debugging messages are enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the
pdnsd status control socket will have. These are the same as
file permissions. The owner of the file will be the run_as user,
or, if none is specified, the user who started pdnsd. If you
want to specify the permissions in octal (as usual), don’t for‐
get the leading zero (0600 instead of 600!). To use the status
control, write access is needed. The default is 0600 (only the
owner may read or write).
Please note that the socket is kept in the cache directory, and
that the cache directory permissions might also need to be
adjusted. Please ensure that the cache directory is not write‐
able for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that
will be active simultaneously. If this number is exceeded,
queries are queued and may be delayed some time. See also the
procq_limit option.
The default for this option is 40.
procq_limit=number;
When the query thread limit proc_limit is exceeded, connection
attempts to pdnsd will be queued. With this option, you can set
the maximum queue length. If this length is also exceeded, the
incoming queries will be dropped. That means that tcp connec‐
tions will be closed and udp queries will just be dropped, which
will probably cause the querying resolver to wait for an answer
until it times out.
See also the proc_limit option. A maximum of
proc_limit+procq_limit query threads will exist at any one time
(plus 3 to 6 threads that will always be present depending on
your configuration).
The default for this option is 60.
tcp_qtimeout=timespec;
This option sets a timeout for tcp queries. If no full query has
been received on a tcp connection after that time has passed,
the connection will be closed. The default is set using the
--with-tcp-qtimeout option to configure.
par_queries=number;
This option used to set the maximum number of remote servers
that would be queried simultaneously, for every query that pdnsd
receives.
Since version 1.1.11, the meaning of this option has changed
slightly. It is now the increment with which the number of par‐
allel queries is increased when the previous set of servers has
timed out. For example, if we have a list server1, server2,
server3, etc. of available servers and par_queries=2, then pdnsd
will first send queries to server1 and server2, and listen for
responses from these servers.
If these servers do not send a reply within their timeout
period, pdnsd will send additional queries to server3 and
server4, and listen for responses from server1, server2, server3
and server4, and so on until a useful reply is received or the
list is exhausted.
In the worst case there will be pending queries to all the
servers in the list of available servers. We may be using more
system resources this way (but only if the first servers in the
list are slow or unresponsive), but the advantage is that we
have a greater chance of catching a reply. After all, if we
wait longer anyway, why not for more servers.
See also the explanation of the global timeout option below.
1 or 2 are good values for this option. The default is set at
compile time using the --with-par-queries option to configure.
timeout=timespec;
This is the global timeout parameter for dns queries. This
specifies the minimum period of time pdnsd will wait after send‐
ing the first query to a remote server before giving up without
having received a reply. The timeout options in the configura‐
tion file are now only minimum timeout intervals. Setting the
global timeout option makes it possible to specify quite short
timeout intervals in the server sections (see below). This will
have the effect that pdnsd will start querying additional
servers fairly quickly if the first servers are slow to respond
(but will still continue to listen for responses from the first
ones). This may allow pdnsd to get an answer more quickly in
certain situations.
If you use query_method=tcp_udp it is recommended that you make
the global timeout at least twice as large as the largest server
timeout, otherwise pdnsd may not have time to try a UDP query if
a TCP connection times out.
Default value is 0.
randomize_recs=(on|off);
If this option is turned on, pdnsd will randomly reorder the
cached records of one type when creating an answer. This sup‐
ports round-robin DNS schemes and increases fail safety for
hosts with multiple IP addresses, so this is usually a good
idea.
On by default.
query_port_start=number;
If given, defines the start of the port range used for queries
of pdnsd. The value given must be >= 1024. The purpose of this
option is to aid certain firewall configurations that are based
on the source port. Please keep in mind that another application
may bind a port in that range, so a stateful firewall using tar‐
get port and/or process uid may be more effective. In case a
query start port is given pdnsd uses this port as the first port
of a specified port range (see query_port_end) used for queries.
pdnsd will try to randomly select a free port from this range as
local port for the query.
To ensure that there are enough ports for pdnsd to use, the
range between query_port_start and query_port_end should be
adjusted to at least (par_queries * proc_limit). A higher value
is highly recommended, because other applications may also allo‐
cate ports in that range. If possible, this range should be kept
out of the space that other applications usually use.
query_port_end=number;
Only used if query_port_start is given. Defines the last port of
the range started by query_port_start used for querys by pdnsd.
The default is 65535, which is also the maximum legal value for
this option. For details see the description of
query_port_start.
delegation_only=string;
Added by Paul Rombouts: This option specifies a "delegation-
only" zone. This means that if pdnsd receives a query for a
name that is in a subdomain of a "delegation-only" zone but the
remote name server returns an answer with an authority section
lacking any NS RRs for subdomains of that zone, pdnsd will
answer NXDOMAIN (unknown domain). This feature can be used for
undoing the undesired effects of DNS "wildcards". Several "dele‐
gation-only" zones may be specified together. If you specify
root servers in a server section it is important that you set
root_server=on in such a section.
Example:
delegation_only="com","net";
This feature is off by default. It is recommended that you only
use this feature if you actually need it, because there is a
risk that some legitimate names will be blocked, especially if
the remote name servers queried by pdnsd return answers with
empty authority sections.
ipv4_6_prefix=string;
This option has the same effect as the -i command-line option.
When pdnsd runs in IPv6 mode, this option specifies the prefix
pdnsd uses to convert IPv4 addresses in the configuration file
(or addresses specified with pdnsd-ctl) to IPv6-mapped
addresses. The string must be a valid IPv6 address. Only the
first 96 bits are used. Note that this only effects the parsing
of IPv4 addresses listed after this option.
The default is "::ffff.0.0.0.0".
server Section
Each server section specifies a set of name servers that pdnsd should
try to get resource records or authoritative name server information
from. The servers are queried in the order of their appearance (or par‐
allel to a limited extend). If one fails, the next one is taken and so
on.
You probably want to specify the dns server in your LAN, the caching
dns servers of your internet provider or even a list of root servers in
one or more server sections.
The supported options in this section are:
label=string;
Specify a label for the server section. This can be used to
refer to this section when using pdnsd-ctl, the pdnsd control
utility.
You can give several server sections the same label, but if you
want to change the addresses of a server section (see ip option
below) during run-time with
"pdnsd-ctl server label up dns1,dns2,...", the label must be
unique.
ip=string;
Give the IP (the IP, not the host name) of the server.
Multiple IP addresses can be given per server section. This can
be done by entering multiple lines of the form ip=string; or a
single line like this:
ip=string,string,string;
IP addresses do not have to be specified in the configuration
file. A server section without IP addresses will remain inac‐
tive until it is assigned one or more addresses with pdnsd-ctl,
the pdnsd control utility.
If pdnsd has been compiled with both IPv4 and IPv6 support, any
IPv6 addresses you specify here will be skipped with a warning
message, unless pdnsd is running in IPv6 mode. Thus, unless
pdnsd was compiled to startup in IPv6 mode by default, you need
to use the command-line option -6 or set run_ipv4=off first (see
global section) in order to ensure that IPv6 addresses are
parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address
here, it will automatically be mapped to an IPv6 address.
file=string;
New in version 1.2: This option allows you to give the name of a
resolv.conf-style file. Of the lines beginning with the name‐
server keyword, the second field will be parsed as an IP
address, as if it were specified with the ip= option. The
remaining lines will be ignored. If the contents of the file
changes while pdnsd is running, you can make pdnsd aware of the
changes through the use of pdnsd-ctl, the pdnsd control utility.
This is usually most conveniently done by placing the command
"pdnsd-ctl config" in a script that is automatically run when‐
ever the DNS configuration changes.
For example, suppose you have a ppp client that writes the DNS
configuration for your ISP to the file /etc/ppp/resolv.conf and
runs the script /etc/ppp/ip-up when a new connection is estab‐
lished. One way of ensuring that pdnsd is automatically recon‐
figured is to add a server section in the config file with
file=/etc/ppp/resolv.conf and to add the command
"pdnsd-ctl config" to /etc/ppp/ip-up.
port=number;
Give the port the remote name server listens on. Default is 53
(the official dns port)
uptest=(ping|none|if|dev|diald|exec|query);
Determine the method to check whether the server is available.
Currently defined methods are:
· ping: Send an ICMP_ECHO request to the server. If it doesn’t
respond within the timeout, it is regarded to be unavailable
until the next probe.
· none: The availability status is not changed, only the time
stamp is updated.
· if: Check whether the interface (specified in the interface=
option) is existent, up and running. This currently works for
all "ordinary" network interfaces, interfaces that disappear
when down (e.g. ppp?), and additionally for Linux isdn inter‐
faces (as of kernel 2.2). Note that you need a /dev/isdninfo
device file (major#45, minor#255), or the isdn uptest will
always fail.
· dev and diald: Perform an if uptest, and, if that was succes‐
ful, additionally check whether a program is running that has
locked a given (modem-) device. The needed parameters are an
interface (specified as for the if uptest, e.g. "ppp0") and a
device relative to /dev (e.g. "modem" for /dev/modem specified
using the device= option. pdnsd will then look for a pid file
for the given interface in /var/lock (e.g. /var/run/ppp0.pid)
and for a lockfile for the given device (e.g.
/var/lock/LCK..modem), and then test whether the locking process
is the process that created the pid file and this process is
still alive. If this is the case, the normal if uptest is exe‐
cuted for the given interface.
The dev option is for pppd dial-on-demand, diald is the same for
diald users.
· exec: Executes a given command in the /bin/sh shell (as
/bin/sh -c <command>) and evaluates the result (the return code
of the last command) in the shell’s way of handling return
codes, i.e. 0 indicates success, all other indicate failure. The
shell’s process name will be uptest_sh. The command is given
with the uptest_cmd option (see below). For secuity issues,
also see that entry.
· query: New in version 1.2: This works like the ping test,
except it sends an empty DNS query to the remote server. If the
server sends a well-formed response back within the timeout
period (except SERVFAIL), it will be regarded as available.
This test is useful if a remote server does not respond to
ICMP_ECHO requests at all, which unfortunately is quite common
these days. In many cases this test will be a more reliable
indicator of availability than the ones mentioned before.
The default value is none.
NOTE: If you use on-demand dialing, use none, if, dev, diald or
exec, since ping or query will send packets in the specified
interval and the interface will thus frequently dial!
ping_timeout=number;
Sets the timeout for the ping test in tenth of seconds. The
default is 600 (one minute).
ping_ip=string;
The ip for the ping test. The default is the ip of the name
server.
uptest_cmd=string,string;
or
uptest_cmd=string;
Sets the command for the uptest=exec function to the first
string. If the second string is given, it specifies a user with
whose user id and primary group id the command is executed.
This is especially useful if you are executing the server as
root, but do not want the uptest to be performed with root priv‐
ileges. In fact, you should never execute the uptest as root if
you can help it.
If the server is running setuid or setgid, the privileges thus
gained are attempted to be dropped even before changing identity
to the specified user to prevent setuid/gid security holes (oth‐
erwise, any user might execute commands as root if you setuid
the executable).
Note that this is not always possible, and that pdnsd should
never be installed as setuid or setgid. The command is executed
using /bin/sh, so you should be able to use shell builtin com‐
mands.
interval=(timespec|onquery|ontimeout);
Sets the interval for the server up-test. The default is 900
seconds; however, a test is forced when a query times out and
the timestamp is reset then.
If you specify onquery instead of a timeout, the interface will
be tested before every query. This is to prevent automatically
dialing interfaces (diald/pppd or ippp) to dial on dns queries.
It is intended to be used in connection with an interface-test‐
ing uptest ;-)
Note that using uptest=exec, you might run into performance
problems on slow machines when you use that option. DON’T use
onquery with uptest=ping or uptest=query, as it may cause delays
if the server does not answer (btw, it doesn’t make sense any‐
way). Note also that using onquery is no guarantee that the
interface will not be used. When another (reachable) dns server
tells pdnsd to query a third dns server for data, pdnsd will do
that and has no means of checking whether this will dial up the
interface or not. This however should be a rare situation.
New in version 1.2.3: A third possibility is to specify inter‐
val=ontimeout. In this case the server is not tested at
startup/reconfiguration, nor at regular intervals, but only
after a DNS query to a server times out. Certain types of net‐
work problems such as a refused connection will also cause the
server to be considered unavailable. However, once a server is
declared dead it is never considered again unless it is revived
using a pdnsd-ctl config or server command. The idea behind
this option is to minimize uptests by assuming all servers are
available until there is reason to believe otherwise.
interface=string;
The network interface (or network device, e.g. "eth0") for the
uptest=if option. Must be specified if uptest=if is given.
device=string;
The (modem-) device that is used for the dev uptest. If you use
this for a dial-on-demand ppp uptest (together with uptest=dev),
you need to enter the device you are using for your pppd here,
e.g. modem for /dev/modem.
Must be specified if uptest=dev is given.
timeout=timespec;
Set the timeout for the dns query. The default is 120 seconds.
You probably want to set this lower.
Timeouts specified in the configuration file are only treated as
the minimum period of time to wait for a reply. A queries to a
remote server are not canceled until a useful reply has been
received, or all the other queries have timed out or failed.
If you have also set the global timeout option, you may consider
setting a fairly small value here. See the explanation of the
timeout option in the global section for what that means.
purge_cache=(on|off);
In every fetched dns record, there is a cache timeout given,
which specifies how long the fetched data may be cached until it
needs to be reloaded. If purge_cache is set to off, the cached
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).
caching=(on|off);
Specifies if caching shall be performed for this server at all.
Default is on.
lean_query=(on|off);
Specifies whether to use the "lean" query mode. In this mode,
only the information actually queried from pdnsd is resolved and
cached. This has the advantage that usually less cache space is
used and the query is usually faster. In 90% of the cases, only
address (A) records are needed anyway. If switched off, pdnsd
will always cache all data about a host it can find and will
specifically ask for all available records (well, at least it is
a good approximation for what it really does ;-) This will of
course increase the answer packet sizes.
Negative caching is only effective with lean_query activated.
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 turn‐
ing this option off.
A last note: If you use multiple pdnsd’s that access each other,
turning this option on is probably a big win.
This on by default.
scheme=string;
You can specify a pcmcia-cs scheme that is used in addition to
the uptests. If you specify a scheme here, the server this sec‐
tion is for will only be queries if the given scheme is active.
Shell wildcards (* and ?) are allowed in the string under their
special meanings. You need to use the scheme_file option on the
global section to make this option work.
preset=(on|off);
This allows you to specify the initial state of a server before
any uptest is performed. on specifies that the server is
regarded available. The default is on. This is especially useful
when you set uptest=none; and want to control a server only via
pdnsd-ctl.
proxy_only=(on|off);
When this option is set to on, answers given by the servers are
always accepted, and no other servers (as, for example, speci‐
fied in the NS records of the query domain) are queried. If you
do not turn this option on, pdnsd will do such queries in some
cases (in particular when processing ANY queries).
This option is useful when you do not want pdnsd to make connec‐
tions to outside servers for some reasons (e.g. when a firewall
is blocking such queries).
I recommend that you turn on lean_query when using this option.
Default is off.
root_server=(on|off);
New in version 1.2: Set this option to on if the servers speci‐
fied in a section are root servers. A root server will typically
only give the name servers for the top-level domain in its
reply. Setting root_server=on will cause pdnsd to try to use
cached information about top-level domains to reduce to number
of queries to root servers, making the resolving of new names
more efficient. You can get a list of available root servers by
running the command "dig -t ns .".
This option is also necessary if you use the delegation_only
option.
Default is off.
policy=(included|excluded|simple_only|fqdn_only);
pdnsd supports inclusion/exclusion lists for server sections:
with include= and exclude= (see below) you can specify domain
names for which this server will be used or will not be used.
The first match counts (i.e., the first include or exclude rule
in a server section that matches a domain name is applied, and
the search for other rules is terminated). If no rule matched a
given domain name, the policy= option determines whether this
server is used for the lookup for that domain name; when
included is given, the server will be asked, and when excluded
is given, it will not. If simple_only is given the server will
be used if the name to lookup is a simple host name, on the
other hand if fqdn_only is given the server will be used only
for fully qualified domain names (i.e. the name has at least one
dot in-between).
If no server is available for a queried domain, pdnsd will
return an error message to the client that usually will stop the
client’s attempts to resolve a specific domain from this server
(the libc resolver will e.g. return an error to the application
that tried to resolve the domain if no other servers are avail‐
able in the resolv.conf). This may be of use sometimes.
Note: the simple_only and fqdn_only constants were added by Paul
Rombouts. They are useful for controlling which name servers
(if any) will be used by pdnsd for simple host names.
The default for this option is included.
include=string;
This option adds an entry to the exclusion/inclusion list. If a
domain matches the name given as string, the server is queried
if this was the first matching rule (see also the entry for pol‐
icy).
If the given name starts with a dot, the whole subdomain of the
given name including the one of that name is matched, e.g.
".foo.bar." will match the domain names a.foo.bar.,
a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name
(ignoring the case, of course) will be matched (hint: if you
want to include all subdomains, but not the domain of the given
name itself, place an exact-match exclude rule before the
include rule, e.g: exclude="foo.bar."; include=".foo.bar.";
Previous versions of pdnsd required that names given with this
and the next option ended in a dot, but since version
1.1.8b1-par8, pdnsd automatically adds a dot at the end if it is
missing.
pdnsd now also accepts a more compact notation for adding sev‐
eral "include" entries in one line, e.g.:
include=".foo",".bar",".my.dom";
exclude=string;
This option adds an entry to the exclusion/inclusion list. If a
domain matches the name given as string, the server is not
queried if this was the first matching rule (see also the entry
for policy).
If the given name starts with a dot, the whole subdomain of the
given name including the one of that name is matched, e.g.
".foo.bar." will match the domain names a.foo.bar.,
a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name
(ignoring the case, of course) will be matched (hint: if you
want to exclude all subdomains, but not the domain of the given
name itself, place an exact-match include rule before the
exclude rule, e.g: include="foo.bar."; exclude=".foo.bar.";
pdnsd now also accepts a more compact notation for adding sev‐
eral "exclude" entries in one line, e.g.:
exclude=".foo",".bar",".my.dom";
rr Section
Every rr section specifies a dns resource record that is stored
locally. It allows you to specify own dns records that are served by
pdnsd in a limited way. Only A, PTR, CNAME, MX, NS and SOA records are
implemented.
This option is intended to allow you to define RRs for 1.0.0.127.in-
addr.arpa. and localhost. (and perhaps even one or two hosts) without
having to start an extra named if your cached name servers do not serve
those records. It is NOT intended and not capable to work as a full-
featured name server.
name=string;
Specifies the name of the resource records, i.e. the domain name
of the resource the record describes. This option must be speci‐
fied before any a, ptr, cname, mx, ns or soa records. Names are
interpreted as absolute domain names (i.e. pdnsd assumes they
end in the root domain). For this and all following arguments
that take domain names, you need to specify domain names in dot‐
ted notation (example venera.isi.edu.).
Previous versions of pdnsd required that domain names given in
the configuration file ended in a dot, but since version
1.1.8b1-par8, pdnsd automatically assumes a dot at the end if it
is missing.
New in version 1.2: It is also possible to specify a name start‐
ing with the label *. Such a name is called a wildcard. The * in
a wildcard can match one or more labels in a queried name, but
only whole labels. Any other * characters in a wildcard, apart
from the leading one, will only match a literal *.
For example, *.mydomain will match a.mydomain or www.a.mydomain,
but not mydomain. *.a*.mydomain will match www.a*.mydomain, but
not www.ab.mydomain. *a.mydomain will only match itself.
Before you can specify an rr section with name=*.mydomain you
must define some records for mydomain, typically NS and/or SOA
records. Example:
rr {
name = mydomain;
ns = localhost;
soa = localhost, root.localhost, 42, 86400, 900, 86400,
86400;
}
rr {
name = *.mydomain;
a = 192.168.1.10;
}
In this example, www.mydomain and ftp.mydomain will resolve to
the numeric address 192.168.1.10 (unless you add rr sections
explicitly specifying different addresses for www.mydomain or
ftp.mydomain). If you want mydomain also to resolve to a
numeric address, add an A record to the first rr section.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in
this section after this entry. This may be redefined. The
default is 86400 seconds (=1 day).
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local
records for this rr section. This means that pdnsd flags the
domain record so that records of this domain that are not
present in the cache are treated as non-existent, i.e. no other
servers are queried for that record type, and an response con‐
taining 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 (and no IPv6 address), you normally don’t want
other name servers to be queried for it.
This is on by default.
Please note that this only has an effect if it precedes the name
option!
reverse=(on|off);
New in version 1.2: If you want a locally defined name to
resolve to a numeric address and vice versa, you can achieve
this by setting reverse=on before defining the A record (see
below). The alternative is to define a separate PTR record, but
you will probably find this option much more convenient.
The default is off.
a=string;
Defines an A (host address) record. The argument is an IP in
dotted notation. pdnsd will serve this address for the host name
given in the name option.
ptr=string;
Defines a PTR (domain name pointer) record. The argument is a
host name in dotted notation (see name). The ptr record is for
resolving adresses into names. For example, if you want the
adress 127.0.0.1 to resolve into localhost, and localhost into
127.0.0.1, you need something like the following sections:
rr {
name = localhost;
a = 127.0.0.1;
owner = localhost;
soa = localhost, root.localhost, 42, 86400, 900, 86400,
86400;
}
rr {
name = 1.0.0.127.in-addr.arpa;
ptr = localhost;
owner = localhost;
soa = localhost, root.localhost, 42, 86400, 900, 86400,
86400;
}
The second section is for reverse resolving and uses the ptr
option. Note that you can get the same effect by specifying
only the first rr section with reverse=on.
There is something special about the name in the second section:
when a resolver wants to get a host name from an internet
address, it composes an address that is built of the IP address
in reverse byte order (1.0.0.127 instead of 127.0.0.1) where
each byte of the adress written as number constitutes a sub-
domain under the domain in-addr.arpa.
So, if you want to compose an adress for reverse resolving, take
your ip in dotted notation (e.g. 1.2.3.4), reverse the byte
order (4.3.2.1) and append in-addr.arpa. (4.3.2.1.in-addr.arpa.)
Then, define an rr section giving this address as name and the
domain name corresponding to that ip in the ptr option.
cname=string;
Defines a CNAME (canonical name) record. The argument should be
a fully-qualified host name in dotted notation (see name). A
CNAME is the DNS equivalent of an alias or symbolic link.
A useful application for CNAMEs is giving short, easy to remem‐
ber nicknames to hosts with complicated names. For example, you
might want the name "news" to refer to your ISP’s news server
"nntp2.myisp.com". Instead of adding an A record for "news"
with the same address as "nntp2.myisp.com", you could put in a
CNAME pointing to "nntp2.myisp.com", so that if the IP address
of the news server changes, there is no need to update the
record for "news".
To implement this with pdnsd, you could add the following sec‐
tion to your configuration file:
rr {
name = news;
cname = nntp2.myisp.com;
owner = localhost;
}
mx=string,number;
Defines an MX (mail exchange) record. The string is the host
name of the mail server in dotted notation (see name). The num‐
ber specifies the preference level.
When you send mail to someone, your mail typically goes from
your E-mail client to an SMTP server. The SMTP server then
checks for the MX record of the domain in the E-mail address.
For example, with joe@example.com, it would look for the MX
record for example.com and find that the name of mail server for
that domain is, say, mail.example.com. The SMTP server then
gets the A record for mail.example.com, and connects to the mail
server.
If there are multiple MX records, the SMTP server will pick one
based on the preference level (starting with the lowest prefer‐
ence number, working its way up).
Don’t define MX records with pdnsd unless you know what you’re
doing.
owner=string;
or
ns=string;
Defines an NS (name server) record. Specifies the name of the
host which should be authoritative for the records you defined
in the rr section. This is typically the host pdnsd runs on.
Note: In previous versions of pdnsd this option had to be speci‐
fied before any a, ptr, cname, mx or soa entries. In version
1.2, the restrictions on this option are same as the options
just mentioned, and it must listed after the name= option. This
can be a pain if you want to use an old config file which speci‐
fies owner= before name= (sorry about that). Apart from greater
consistency, the advantage is that you can now specify as many
NS records as you like (including zero).
soa=string,string,number,timespec,timespec,timespec,timespec;
This defines a soa (start of authority) record. The first string
is the domain name of the server and should be equal to the name
you specified as owner.
The second string specifies the email address of the maintainer
of the name server. It is also specified as a domain name, so
you will have to replace the @ sign in the name with a dot (.)
to get the name you have to specify here. The next parameter
(the first number) is the serial number of the record. You
should increment this number if you change the record.
The 4th parameter is the refresh timeout. It specifies after
what amount of time a caching server should attempt to refresh
the cached record.
The 5th parameter specifies a time after which a caching server
should attempt to refresh the record after a refresh failure.
The 6th parameter defines the timeout after which a cached
record expires if it has not been refreshed.
The 7th parameter is the ttl that is specified in every rr and
should be the same as given with the ttl option (if you do not
specify a ttl, use the default 86400)
neg Section
Every neg section specifies a dns resource record or a dns domain that
should be cached negatively locally. Queries for negatively cached
records are always answered immediatley with an error or an empty
answer without querying other hosts as long as the record is valid. The
records defined with neg sections remain valid until they are
explicitely invalidated or deleted by the user using pdnsd-ctl.
This is useful if a certain application asks periodically for nonexist‐
ing 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 outgo‐
ing queries for these by specifying
neg {
name = news;
types = domain;
}
neg {
name = mail;
types = domain;
}
in your config file. If you have a search list, you have to repeat that
for any entry in your search list in addition to the entries given
above!
In versions 1.1.11 and later, if you negate whole domains this way, all
subdomains will be negated as well. Thus if you specify
neg {name=example.com; types=domain;} in the config file, this will
also negate www.example.com, xxx.adserver.example.com, etc.
name=string;
Specifies the name of the domain for which negative cache
entries are created. This option must be specified before the
types option. Names are interpreted as absolute domain names
(i.e. pdnsd assumes they end in the root domain). You need to
specify domain names in dotted notation (example ven‐
era.isi.edu.).
Previous versions of pdnsd required that domain names given in
the configuration file ended in a dot, but since version
1.1.8b1-par8, pdnsd automatically assumes a dot at the end if it
is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in
this section after this entry. This may be redefined. The
default is 86400 seconds (=1 day).
types=(domain|rr_type[,rr_type[,rr_type[,...]]]);
Specifies what is to be cached negatively: domain will cache the
whole domain negatively; alternatively, you can specify a comma-
separated list of RR types which are to be cached negatively.
You may specify multiple types options, but domain and the RR
types are mutually exclusive.
The RR types are specified using their official names from the
RFC’s in capitals, e.g. A, CNAME, NS, PTR, MX, AAAA, ...
The command pdnsd-ctl list-rrtypes will give you a complete list
of those types. pdnsd-ctl is built along with pdnsd and will be
installed in the same directory as the pdnsd binary during make
install.
source Section
Every source section allows you to let pdnsd read the records from a
file in an /etc/hosts-like format. pdnsd will generate records to
resolve the entries address from its host name and vice versa for every
entry in the file. This is normally easier than defining an rr for
every of your addresses, since localhost and your other FQDNs are nor‐
mally given in /etc/hosts.
The accepted format is as follows: The #-sign initiates a comment, the
rest of the line from the first occurence of this character on is
ignored. Empty lines are tolerated.
The first entry on a line (predeceded by an arbitrary number of tabs
and spaces) is the IP in dotted notation, the second entry on one line
(separated by the first by an arbitrary number of tabs and spaces) is
the FQDN (fully qualified domain name) for that ip. The rest of the
line is ignored by default (in the original /etc/hosts, it may contain
information not needed by pdnsd).
owner=string;
Specifies the name of the host pdnsd runs on and that are speci‐
fied in dns answers (specifically, nameserver records). Must be
specified before any file entries.
Names are interpreted as absolute domain names (i.e. pdnsd
assumes they end in the root domain). You need to specify
domain names in dotted notation (example venera.isi.edu.).
Previous versions of pdnsd required that domain names given in
the configuration file ended in a dot, but since version
1.1.8b1-par8, pdnsd automatically assumes a dot at the end if it
is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in
this section after this entry. This may be redefined. The
default is 86400 seconds (=1 day).
file=string;
The string specifies a file name. For every file entry in a
source section, pdnsd will try to load the given file as
described above. Failure is indicated only when the file cannot
be opened, malformed entries will be ignored.
serve_aliases=(on|off);
If this is turned on pdnsd will serve the aliases given in a
hosts-style file. These are the third entry in a line of a
hosts-style file, which usually give a "short name" for the
host. This may be used to support broken clients without a
proper domain-search option. If no aliases are given in a line
of the file, pdnsd behaves as without this option for this line.
This feature was suggested by Bert Frederiks.
It is off by default.
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local
records with the data from the hosts file. Please see the
description of the option of the same name in the rr section for
a closer description of what this means. Please note that this
only has an effect for files sourced with