Provided by: pdnsd_1.2.9a-par-2_amd64 
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 prefixed with the section
name and opening curlies ({) and closed with closing curlies (}). In each section,
configuration options can be given in the form
option_name=option_value;
Option value may be a string literal, a number, a time specification or a constant. In
previous versions of pdnsd strings had to be enclosed in quotes ("), but since version
1.1.10 this is no longer necessary, unless a string contains a special character such as
whitespace, a token that normally starts a comment, or one of ",;{} Since version 1.2.9 a
backslash ( inside a string is interpreted as an escape character, so it is possible to
include special characters in strings (both quoted or unquoted) by preceding them with a
backslash. Some escape sequences are in interpreted as in the C programming language, e.g.
\t becomes a tab, \n becomes a new-line control char.
A time specification consists a sequence of digits followed by a one-letter suffix. The
following suffixes are recognized: s (seconds), m (minutes), h (hours), d (days) and w
(weeks). If the suffix is missing, seconds are assumed. If several time specifications
are concatenated, their values are added together; e.g. 2h30m is interpreted as 2*60*60 +
30*60 = 9000 seconds.
Some options take more than one value; in this case, the values are separated with commas.
If you may supply one of a set of possible values to an option, this is noted in the
documentation as (option1|option2|option3|...)
The constants true|false and yes|no are accepted as synonyms for the constants on|off.
Comments may be enclosed in /* and */, nested comments are possible. If the # sign or two
slashes (//) appear in the configuration file, everything from these signs to the end of
the current line is regarded as a comment and ignored.
There are examples for nearly all options in the sample config file.
global Section
The global section specifies parameters that affect the overall behaviour of the server.
If you specify multiple global sections, the settings of those later in the file will
overwrite the earlier given values.
These are the possible options:
perm_cache=(number|off);
Switch the disk cache off or supply a maximum cache size in kB. If the disk cache
is switched off, 8 bytes will still be written to disk. The memory cache is always
10kB larger than the file cache. This value is 2048 (2 MB) by default.
cache_dir=string;
Set the directory you want to keep the cache in. The default is "/var/cache/pdnsd"
(unless pdnsd was compiled with a different default).
server_port=number;
Set the server port. This is especially useful when you want to start the server
and are not root. Note that you may also not specify uptest=ping in the server
section as non-root.
The default port is 53, the RFC-standard one. Note that you should only use non-
standard ports when you only need clients on your machine to communicate with the
server; others will probably fail if the try to contact the server on the basis of
an NS record, since the A record that supplies the address for (among others) name
servers does not have a port number specification.
server_ip=string;
or
interface=string;
Set the IP address pdnsd listens on for requests. This can be useful when the host
has several interfaces and you want pdnsd not to listen on all interfaces. For
example, it is possible to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a
forwarder for BIND. The default setting for this option is server_ip=any, which
means that pdnsd will listen on all of your local interfaces. Presently you can
only specify one address here; if you want pdnsd to listen on multiple interfaces
but not all you will have to specify server_ip=any and use firewall rules to
restrict access.
The IP address used to need quotation marks around it, but since version 1.1.10
this is no longer necessary.
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to specify
an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode by
default, you will need to use the -6 command-line option or set run_ipv4=off first
(see below) in order to ensure that the IPv6 address is parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will
automatically be mapped to an IPv6 address.
New in version 1.2: You may also give the name of an interface such as "lo" or
"eth0" here, instead of an IP address (this has been tested on Linux, and may or
may not work on other platforms). pdnsd will not bind to the interface name, but
will look up the address of the interface at start-up and listen on that address.
If the address of the interface changes while pdnsd is running, pdnsd will not
notice that. You will need to restart pdnsd in that case.
outgoing_ip=string;
or
outside_interface=string;
New in version 1.2.9: Set the IP address of the interface used by pdnsd for
outgoing queries. This can be useful when the host has several interfaces and you
want pdnsd to send outgoing queries via only one of them. For example, if pdnsd
is running on a host with one interface with IP address 192.168.1.1 connected to
the local network, and another with IP address 123.xxx.yyy.zzz connected to the
internet, you may specify server_ip=192.168.1.1 and outgoing_ip=123.xxx.yyy.zzz to
enforce that pdnsd only responds to queries received from the local network, and
only sends outgoing queries via the interface connected to the internet.
The default setting for this option is any, which means that the kernel is free to
decide which interface to use. Like with the server_ip option, you may also give
the name of an interface here, instead of an IP address.
linkdown_kluge=(on|off);
This option enables a kluge that some people might need: when all servers are
marked down, with this option set the cache is not even used when a query is
received, and a DNS error is returned in any case. The only exception from this is
that local records (as specified in rr and source sections are still served
normally. In general, you probably want to get cached entries even when the
network is down, so this defaults to off.
max_ttl=timespec;
This option sets the maximum time a record is held in cache. All dns resource
records have a time to live field that says for what period of time the record may
be cached before it needs to be requeried. If this is more than the value given
with max_ttl, this time to live value is set to max_ttl. This is done to prevent
records from being cached an inappropriate long period of time, because that is
almost never a good thing to do. Default is 604800s (one week).
min_ttl=timespec;
This option sets the minimum time a record is held in cache. All dns resource
records have a time to live field that says for what period of time the record may
be cached before it needs to be requeried. If this is less than the value given
with min_ttl, this time to live value is set to min_ttl. Default is 120 seconds.
neg_ttl=timespec;
This option sets the time that negatively cached records will remain valid in the
cache if no time to live can be determined. This is always the case when whole
domains are being cached negatively, and additionally when record types are cached
negatively for a domain for which no SOA record is known to pdnsd. If a SOA is
present, the ttl of the SOA is taken.
neg_rrs_pol=(on|off|auth|default);
This sets the RR set policy for negative caching; this tells pdnsd under which
circumstances it should cache a record type negatively for a certain domain. off
will turn the negative caching of record types off, on will always add a negative
cache entry when a name server did not return a record type we asked it for, and
auth will only add such entries if the answer came from an authoritative name
server for that domain.
New in version 1.2.8: The default setting will add a negatively cached record if
either the answer was authoritive or the answer indicated the name server had
"recursion available" while the query explicitly requested such recursion.
The preset is "default" (used to be auth).
neg_domain_pol=(on|off|auth);
This is analogue to neg_rrs_pol for whole domain negative caching. It should be
safe to set this on, because I have not seen a caching server that will falsely
claim that a domain does not exist.
The default is auth.
run_as=string;
This option allows you to let pdnsd change its user and group id after operations
that needed privileges have been done. This helps minimize security risks and is
therefore recommended. The supplied string gives a user name whose user id and
primary group id are taken.
A little more details: after reading the config file, becoming a daemon (if
specified) and starting the server status thread, the main thread changes its gid
and uid, as do all newly created threads thereafter. By taking another uid and gid,
those threads run with the privileges of the specified user. Under Linux and
FreeBSD, the server status thread runs with the original privileges only when the
strict_setuid option is set to off (see below, on by default), because these may be
needed for exec uptests. The manager thread also retains its original privileges in
this case. You should take care that the user you specify has write permissions on
your cache file and status pipe (if you need a status pipe). You should look out
for error messages like "permission denied" and "operation not permitted" to
discover permission problems.
strict_setuid=(on|off);
When used together with the run_as option, this option lets you specify that all
threads of the program will run with the privileges of the run_as user. This
provides higher security than the normal run_as option, but is not always possible.
See the run_as option for further discussion.
This option is on by default.
Note that this option has no effect on Non-Linux systems.
paranoid=(on|off);
Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to
query other servers themselves if possible, and to give back answers for domains
that may not be in its authority), and accepts additional records with information
for servers that are not in the authority of the queried server. This opens the
possibility of so-called cache poisoning: a malicious attacker might set up a dns
server that, when queried, returns forged additional records. This way, he might
replace trusted servers with his own ones by making your dns server return bad IP
addresses. This option protects you from cache poisoning by rejecting additional
records that do not describe domains in the queried servers authority space and not
doing recursive queries any more. An exception to this rule are the servers you
specify in your config file, which are trusted.
The penalty is a possible performance decrease, in particular, more queries might
be necessary for the same operation.
You should also notice that there may be other similar security problems, which are
essentially problems of the DNS, i.e. any "traditional" server has them (the DNS
security extensions solve these problems, but are not widely supported). One of
this vulnerabilities is that an attacker may bombard you with forged answers in
hopes that one may match a query you have done. If you have done such a query, one
in 65536 forged packets will be successful (i.e. an average packet count of 32768
is needed for that attack). pdnsd can use TCP for queries, which has a slightly
higher overhead, but is much less vulnerable to such attacks on sane operating
systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a
shortcut. If the attacker is able to listen to your network traffic, this attack is
relatively easy, though.
This vulnerability is not pdnsd's fault, and is possible using any conventional
name server (pdnsd is perhaps a little more secured against this type of attacks if
you make it use TCP).
The paranoid option is off by default.
ignore_cd=(on|off);
New in version 1.2.8: This option lets you specify that the CD bit of a DNS query
will be ignored. Otherwise pdnsd will reply FORMERR to clients that set this bit
in a query. It is safe to enable this option, as the CD bit refers to 'Checking
Disabled' which means that the client will accept non-authenticated data.
This option is on by default. Turn it off if you want the old behaviour (before
version 1.2.8).
scheme_file=string;
In addition to normal uptests, you may specify that some servers shall only be
queried when a certain pcmcia-cs scheme is active (only under linux). For that,
pdnsd needs to know where the file resides that holds the pcmcia scheme
information. Normally, this is either /var/lib/pcmcia/scheme or
/var/state/pcmcia/scheme.
status_ctl=(on|off);
This has the same effect as the -s command line option: the status control is
enabled when on is specified.
Added by Paul Rombouts: Note that pdnsd-ctl allows run-time configuration of pdnsd,
even the IP addesses of the name servers can be changed. If you're not using
pdnsd-ctl and you want maximum security, you should not enable this option. It is
disabled by default.
daemon=(on|off);
This has the same effect as the -d command line option: the daemon mode is enabled
when on is specified.
Default is off.
tcp_server=(on|off);
tcp_server=on has the same effect as the -t or --tcp command-line option: it
enables TCP serving. Similarly, tcp_server=off is like the --notcp command-line
option.
Default is on.
pid_file=string;
This has the same effect as the -p command line option: you can specify a file that
pdnsd will write its pid into when it starts in daemon mode.
verbosity=number;
This has the same effect as the -v command line option: you can set the verbosity
of pdnsd's messages with it. The argument is a number between 0 (few messages) to 3
(most messages).
query_method=(tcp_only|udp_only|tcp_udp|udp_tcp);
This has the same effect as the -m command line option. Read the documentation for
the command line option on this. tcp_only corresponds to the to, udp_only to the
uo, tcp_udp to the tu and udp_tcp to the ut argument of the command line option.
If you use query_method=tcp_udp, it is recommended that you also set the global
timeout option to at least twice the longest server timeout.
run_ipv4=(on|off);
This has the same effect as the -4 or -6 command line option: if on is specified,
IPv4 support is enabled, and IPv6 support is disabled (if available). If off is
specified, IPv4 will be disabled and IPv6 will be enabled. For this option to be
meaningful, pdnsd needs to be compiled with support for the protocol you choose.
If pdnsd was compiled with both IPv4 and IPv6 support, and you want to include IPv6
addresses in the configuration file, you will probably need to specify run_ipv4=off
first to ensure that the IPv6 addresses are parsed correctly.
debug=(on|off);
This has the same effect as the -g command line option: the debugging messages are
enabled when on is specified.
ctl_perms=number;
This option allows you to set the file permissions that the pdnsd status control
socket will have. These are the same as file permissions. The owner of the file
will be the run_as user, or, if none is specified, the user who started pdnsd. If
you want to specify the permissions in octal (as usual), don't forget the leading
zero (0600 instead of 600!). To use the status control, write access is needed. The
default is 0600 (only the owner may read or write).
Please note that the socket is kept in the cache directory, and that the cache
directory permissions might also need to be adjusted. Please ensure that the cache
directory is not writeable for untrusted users.
proc_limit=number;
With this option, you can set a limit on the pdnsd threads that will be active
simultaneously. If this number is exceeded, queries are queued and may be delayed
some time. See also the procq_limit option.
The default for this option is 40.
procq_limit=number;
When the query thread limit proc_limit is exceeded, connection attempts to pdnsd
will be queued. With this option, you can set the maximum queue length. If this
length is also exceeded, the incoming queries will be dropped. That means that tcp
connections will be closed and udp queries will just be dropped, which will
probably cause the querying resolver to wait for an answer until it times out.
See also the proc_limit option. A maximum of proc_limit+procq_limit query threads
will exist at any one time (plus 3 to 6 threads that will always be present
depending on your configuration).
The default for this option is 60.
tcp_qtimeout=timespec;
This option sets a timeout for tcp queries. If no full query has been received on a
tcp connection after that time has passed, the connection will be closed. The
default is set using the --with-tcp-qtimeout option to configure.
par_queries=number;
This option used to set the maximum number of remote servers that would be queried
simultaneously, for every query that pdnsd receives.
Since version 1.1.11, the meaning of this option has changed slightly. It is now
the increment with which the number of parallel queries is increased when the
previous set of servers has timed out. For example, if we have a list server1,
server2, server3, etc. of available servers and par_queries=2, then pdnsd will
first send queries to server1 and server2, and listen for responses from these
servers.
If these servers do not send a reply within their timeout period, pdnsd will send
additional queries to server3 and server4, and listen for responses from server1,
server2, server3 and server4, and so on until a useful reply is received or the
list is exhausted.
In the worst case there will be pending queries to all the servers in the list of
available servers. We may be using more system resources this way (but only if the
first servers in the list are slow or unresponsive), but the advantage is that we
have a greater chance of catching a reply. After all, if we wait longer anyway,
why not for more servers.
See also the explanation of the global timeout option below.
1 or 2 are good values for this option. The default is set at compile time using
the --with-par-queries option to configure.
timeout=timespec;
This is the global timeout parameter for dns queries. This specifies the minimum
period of time pdnsd will wait after sending the first query to a remote server
before giving up without having received a reply. The timeout options in the
configuration file are now only minimum timeout intervals. Setting the global
timeout option makes it possible to specify quite short timeout intervals in the
server sections (see below). This will have the effect that pdnsd will start
querying additional servers fairly quickly if the first servers are slow to respond
(but will still continue to listen for responses from the first ones). This may
allow pdnsd to get an answer more quickly in certain situations.
If you use query_method=tcp_udp it is recommended that you make the global timeout
at least twice as large as the largest server timeout, otherwise pdnsd may not have
time to try a UDP query if a TCP connection times out.
Default value is 0.
randomize_recs=(on|off);
If this option is turned on, pdnsd will randomly reorder the cached records of one
type when creating an answer. This supports round-robin DNS schemes and increases
fail safety for hosts with multiple IP addresses, so this is usually a good idea.
On by default.
query_port_start=(number|none);
If a number is given, this defines the start of the port range used for queries of
pdnsd. The value given must be >= 1024. The purpose of this option is to aid
certain firewall configurations that are based on the source port. Please keep in
mind that another application may bind a port in that range, so a stateful firewall
using target port and/or process uid may be more effective. In case a query start
port is given pdnsd uses this port as the first port of a specified port range (see
query_port_end) used for queries. pdnsd will try to randomly select a free port
from this range as local port for the query.
To ensure that there are enough ports for pdnsd to use, the range between
query_port_start and query_port_end should be adjusted to at least (par_queries *
proc_limit). A larger range is highly recommended for security reasons, and also
because other applications may allocate ports in that range. If possible, this
range should be kept out of the space that other applications usually use.
The default for this option is 1024. Together with the default value of
query_port_end, this makes it the hardest for an attacker to guess the source port
used by the pdnsd resolver. If you specify none here, pdnsd will let the kernel
choose the source port, but this may leave pdnsd more vulnerable to an attack.
query_port_end=number;
Used if query_port_start is not none. Defines the last port of the range started by
query_port_start used for querys by pdnsd. The default is 65535, which is also the
maximum legal value for this option. For details see the description of
query_port_start.
delegation_only=string;
Added by Paul Rombouts: This option specifies a "delegation-only" zone. This means
that if pdnsd receives a query for a name that is in a subdomain of a "delegation-
only" zone but the remote name server returns an answer with an authority section
lacking any NS RRs for subdomains of that zone, pdnsd will answer NXDOMAIN (unknown
domain). This feature can be used for undoing the undesired effects of DNS
"wildcards". Several "delegation-only" zones may be specified together. If you
specify root servers in a server section it is important that you set
root_server=on in such a section.
Example:
delegation_only="com","net";
This feature is off by default. It is recommended that you only use this feature if
you actually need it, because there is a risk that some legitimate names will be
blocked, especially if the remote name servers queried by pdnsd return answers with
empty authority sections.
ipv4_6_prefix=string;
This option has the same effect as the -i command-line option. When pdnsd runs in
IPv6 mode, this option specifies the prefix pdnsd uses to convert IPv4 addresses in
the configuration file (or addresses specified with pdnsd-ctl) to IPv6-mapped
addresses. The string must be a valid IPv6 address. Only the first 96 bits are
used. Note that this only effects the parsing of IPv4 addresses listed after this
option.
The default is "::ffff.0.0.0.0".
use_nss=(on|off);
If this option is turned on, pdnsd will call initgroups() to set up the group
access list, whenever pdnsd changes its user and group id (see run_as option).
There is a possible snag, though, if initgroups() uses NSS (Name Service Switch)
and NSS in turn uses DNS. In such a case you may experience lengthy timeouts and
stalls. By setting use_nss=off, you can disable the initgroups() call (only
possible in versions 1.2.5 and later).
This option was contributed by Jan-Marek Glogowski.
On by default.
udpbufsize=number;
New in version 1.2.9: This option sets the upper limit on the size of UDP DNS
messages. The default is 1024.
See also the edns_query server option below.
server Section
Each server section specifies a set of name servers that pdnsd should try to get resource
records or authoritative name server information from. The servers are queried in the
order of their appearance (or parallel to a limited extend). If one fails, the next one
is taken and so on.
You probably want to specify the dns server in your LAN, the caching dns servers of your
internet provider or even a list of root servers in one or more server sections.
The supported options in this section are:
label=string;
Specify a label for the server section. This can be used to refer to this section
when using pdnsd-ctl, the pdnsd control utility.
You can give several server sections the same label, but if you want to change the
addresses of a server section (see ip option below) during run-time with
"pdnsd-ctl server label up dns1,dns2,...", the label must be unique.
ip=string;
Give the IP (the address, not the host name) of the server.
Multiple IP addresses can be given per server section. This can be done by
entering multiple lines of the form ip=string; or a single line like this:
ip=string,string,string;
IP addresses do not have to be specified in the configuration file. A server
section without IP addresses will remain inactive until it is assigned one or more
addresses with pdnsd-ctl, the pdnsd control utility.
If pdnsd has been compiled with both IPv4 and IPv6 support, any IPv6 addresses you
specify here will be skipped with a warning message, unless pdnsd is running in
IPv6 mode. Thus, unless pdnsd was compiled to startup in IPv6 mode by default, you
need to use the command-line option -6 or set run_ipv4=off first (see global
section) in order to ensure that IPv6 addresses are parsed correctly.
If pdnsd is running in IPv6 mode and you specify an IPv4 address here, it will
automatically be mapped to an IPv6 address.
file=string;
New in version 1.2: This option allows you to give the name of a resolv.conf-style
file. Of the lines beginning with the nameserver keyword, the second field will be
parsed as an IP address, as if it were specified with the ip= option. The remaining
lines will be ignored. If the contents of the file changes while pdnsd is running,
you can make pdnsd aware of the changes through the use of pdnsd-ctl, the pdnsd
control utility. This is usually most conveniently done by placing the command
"pdnsd-ctl config" in a script that is automatically run whenever the DNS
configuration changes.
For example, suppose you have a ppp client that writes the DNS configuration for
your ISP to the file /etc/ppp/resolv.conf and runs the script /etc/ppp/ip-up when a
new connection is established. One way of ensuring that pdnsd is automatically
reconfigured is to add a server section in the config file with
file=/etc/ppp/resolv.conf and to add the command "pdnsd-ctl config" to /etc/ppp/ip-
up.
port=number;
Give the port the remote name server listens on. Default is 53 (the official dns
port)
uptest=(ping|none|if|dev|diald|exec|query);
Determine the method to check whether the server is available. Currently defined
methods are:
• ping: Send an ICMP_ECHO request to the server. If it doesn't respond within the
timeout, it is regarded to be unavailable until the next probe.
• none: The availability status is not changed, only the time stamp is updated.
• if: Check whether the interface (specified in the interface= option) is existent,
up and running. This currently works for all "ordinary" network interfaces,
interfaces that disappear when down (e.g. ppp?), and additionally for Linux isdn
interfaces (as of kernel 2.2). Note that you need a /dev/isdninfo device file
(major#45, minor#255), or the isdn uptest will always fail.
• dev and diald: Perform an if uptest, and, if that was successful, additionally
check whether a program is running that has locked a given (modem-) device. The
needed parameters are an interface (specified as for the if uptest, e.g. "ppp0")
and a device relative to /dev (e.g. "modem" for /dev/modem specified using the
device= option. pdnsd will then look for a pid file for the given interface in
/var/lock (e.g. /var/run/ppp0.pid) and for a lockfile for the given device (e.g.
/var/lock/LCK..modem), and then test whether the locking process is the process
that created the pid file and this process is still alive. If this is the case, the
normal if uptest is executed for the given interface.
The dev option is for pppd dial-on-demand, diald is the same for diald users.
• exec: Executes a given command in the /bin/sh shell (as /bin/sh -c <command>) and
evaluates the result (the return code of the last command) in the shell's way of
handling return codes, i.e. 0 indicates success, all other indicate failure. The
shell's process name will be uptest_sh. The command is given with the uptest_cmd
option (see below). For secuity issues, also see that entry.
• query: New in version 1.2: This works like the ping test, except it sends an
(empty) DNS query to the remote server. If the server sends a well-formed response
back within the timeout period (except SERVFAIL), it will be regarded as available.
This test is useful if a remote server does not respond to ICMP_ECHO requests at
all, which unfortunately is quite common these days. It can also happen that a
remote server is online but ignores empty DNS queries. Then you will need the set
the query_test_name option (see below). In many cases this test will be a more
reliable indicator of availability than the ones mentioned before.
The default value is none.
NOTE: If you use on-demand dialing, use none, if, dev, diald or exec, since ping or
query will send packets in the specified interval and the interface will thus
frequently dial!
ping_timeout=number;
Sets the timeout for the ping test in tenths of seconds (this unit is used for
legacy reasons; actually the current implementation is only accurate to a second).
The default is 600 (one minute).
ping_ip=string;
The IP address for the ping test. The default is the IP of the name server.
query_test_name=string;
New in version 1.2.9: Sets the name to be queried when using uptest=query
availability test. If the string is the unquoted constant none, an empty query is
used (this the default), otherwise a query of type A will be sent for the domain
name specified here. It is not necessary for the domain name to exist or have a
record of type A in order for the uptest to succeed.
If the the remote server ignores empty queries, you will probably want to set
query_test_name="." (the root domain).
uptest_cmd=string,string;
or
uptest_cmd=string;
Sets the command for the uptest=exec function to the first string. If the second
string is given, it specifies a user with whose user id and primary group id the
command is executed.
This is especially useful if you are executing the server as root, but do not want
the uptest to be performed with root privileges. In fact, you should never execute
the uptest as root if you can help it.
If the server is running setuid or setgid, the privileges thus gained are attempted
to be dropped even before changing identity to the specified user to prevent
setuid/gid security holes (otherwise, any user might execute commands as root if
you setuid the executable).
Note that this is not always possible, and that pdnsd should never be installed as
setuid or setgid. The command is executed using /bin/sh, so you should be able to
use shell builtin commands.
interval=(timespec|onquery|ontimeout);
Sets the interval for the server up-test. The default is 900 seconds; however, a
test is forced when a query times out and the timestamp is reset then.
If you specify onquery instead of a timeout, the interface will be tested before
every query. This is to prevent automatically dialing interfaces (diald/pppd or
ippp) to dial on dns queries. It is intended to be used in connection with an
interface-testing uptest ;-)
Note that using uptest=exec, you might run into performance problems on slow
machines when you use that option. DON'T use onquery with uptest=ping or
uptest=query, as it may cause delays if the server does not answer (btw, it doesn't
make sense anyway). Note also that using onquery is no guarantee that the
interface will not be used. When another (reachable) dns server tells pdnsd to
query a third dns server for data, pdnsd will do that and has no means of checking
whether this will dial up the interface or not. This however should be a rare
situation.
New in version 1.2.3: A third possibility is to specify interval=ontimeout. In
this case the server is not tested at startup/reconfiguration, nor at regular
intervals, but only after a DNS query to a server times out. Certain types of
network problems such as a refused connection will also cause the server to be
considered unavailable. However, once a server is declared dead it is never
considered again unless it is revived using a pdnsd-ctl config or server command.
The idea behind this option is to minimize uptests by assuming all servers are
available until there is reason to believe otherwise.
interface=string;
The network interface (or network device, e.g. "eth0") for the uptest=if option.
Must be specified if uptest=if is given.
device=string;
The (modem-) device that is used for the dev uptest. If you use this for a dial-on-
demand ppp uptest (together with uptest=dev), you need to enter the device you are
using for your pppd here, e.g. modem for /dev/modem.
Must be specified if uptest=dev is given.
timeout=timespec;
Set the timeout for the dns query. The default is 120 seconds. You probably want to
set this lower.
Timeouts specified in the configuration file are only treated as the minimum period
of time to wait for a reply. A queries to a remote server are not canceled until a
useful reply has been received, or all the other queries have timed out or failed.
If you have also set the global timeout option, you may consider setting a fairly
small value here. See the explanation of the timeout option in the global section
for what that means.
purge_cache=(on|off);
In every fetched dns record, there is a cache timeout given, which specifies how
long the fetched data may be cached until it needs to be reloaded. If purge_cache
is set to off, the stale records are not purged (unless the cache size would be
exceeded, in this case the oldest records are purged). Instead, they are still
served if they cannot successfully be updated (e.g. because all servers are down).
Default is off.
caching=(on|off);
Specifies if caching shall be performed for this server at all. Default is on.
lean_query=(on|off);
Specifies whether to use the "lean" query mode. In this mode, only the information
actually queried from pdnsd is resolved and cached. This has the advantage that
usually less cache space is used and the query is usually faster. In 90% of the
cases, only address (A) records are needed anyway. If switched off, pdnsd will
always cache all data about a host it can find and will specifically ask for all
available records (well, at least it is a good approximation for what it really
does ;-) This will of course increase the answer packet sizes.
Some buggy name servers may not deliver CNAME records when not asked for all
records. I do not know if such servers are around, but if you have trouble
resolving certain host names, try turning this option off.
A last note: If you use multiple pdnsd's that access each other, turning this
option on is probably a big win.
This on by default.
edns_query=(on|off);
New in version 1.2.9: Specifies whether to use EDNS (Extension mechanisms for DNS)
for outgoing queries. Currently this is only useful for allowing UDP message sizes
larger than 512 bytes. Note that setting this option on can give problems in
combination with some legacy systems or software, including, embarrassingly enough,
previous versions of pdnsd.
The default is off, but if your network can handle UDP payloads significantly
larger than 512 bytes, the recommended value is on.
Note that this option only effects outgoing queries. If pdnsd receives a query
using EDNS, it will reply using EDNS regardless of the value of this option.
See also the udpbufsize option above.
scheme=string;
You can specify a pcmcia-cs scheme that is used in addition to the uptests. If you
specify a scheme here, the server this section is for will only be queries if the
given scheme is active. Shell wildcards (* and ?) are allowed in the string under
their special meanings. You need to use the scheme_file option on the global
section to make this option work.
preset=(on|off);
This allows you to specify the initial state of a server before any uptest is
performed. on specifies that the server is regarded available. The default is on.
This is especially useful when you set uptest=none; and want to change the status
of a server only via pdnsd-ctl.
proxy_only=(on|off);
When this option is set to on, answers given by the servers are always accepted,
and no other servers (as, for example, specified in the NS records of the query
domain) are queried. If you do not turn this option on, pdnsd will do such queries
in some cases (in particular when processing ANY queries).
This option is useful when you do not want pdnsd to make connections to outside
servers for some reasons (e.g. when a firewall is blocking such queries).
I recommend that you turn on lean_query when using this option.
Default is off.
root_server=(on|off|discover);
Set this option to on if the servers specified in a section are root servers. A
root server will typically only give the name servers for the top-level domain in
its reply. Setting root_server=on will cause pdnsd to try to use cached
information about top-level domains to reduce to number of queries to root servers,
making the resolving of new names more efficient. You can get a list of available
root servers by running the command "dig . ns".
This option is also necessary if you use the delegation_only option.
New in version 1.2.8: This option may also be set to "discover". This will cause
pdnsd to query the servers provided with the ip= option to obtain the full list of
root servers. The root-server addresses will replace the addresses specified with
the ip= option. This will only be done once on startup, or after a
"pdnsd-ctl config" command. In this case the name servers specified with the ip=
option don't have to be root servers, they just have to know the names and
addresses of the root servers. After root-server discovery pdnsd will behave just
as if root_server=on had been specified.
Default is off.
randomize_servers=(on|off);
New in version 1.2.6: Set this option to on to give each name server in this
section an equal chance of being queried. If this option is off, the name servers
are always queried starting with the first one specified. Even with this option on,
the query order is not truly random. Only the first server is selected randomly;
the following ones are queried in consecutive order, wrapping around to the
beginning of the list when the end is reached. Note that this option only effects
the order within a section. The servers in the first (active) section are always
queried before those in the second one, etc.
The default is off, but if you are resolving from root servers setting this option
on is highly recommended. If root_server=on this option also effects the query
order of the name servers for the top-level domains.
reject=string;
New in version 1.2.6: This option can be used to make pdnsd reject replies that
contain certain IP addresses. You can specify a single IP address, which will be
matched exactly, or a range of addresses using an address/mask pair. The mask can
be specified as a simple integer, indicating the number of initial 1 bits in the
mask, or in the usual IP address notation. IP addresses may be either IPv4 or IPv6
(provided there is sufficient support in the C libraries and support for AAAA
records was not disabled). When addresses in the reject list are compared with
those in a reply, only the bits corresponding to those set in the netmask are
significant, the rest are ignored.
Multiple addresses or address/mask pairs may be specified; this can be done by
entering multiple lines of the form reject=string; or a single line like this:
reject=string,string,string;
How pdnsd reacts when an address in the reply matches one in the reject list,
depends on the reject_policy option, see below.
reject_policy=(fail|negate);
New in version 1.2.6: This option determines what pdnsd does when an address in the
reply from a name server matches the reject list (see above). If this option is set
to fail, pdnsd will try another server, or, if there no more servers to try, return
the answer SERVFAIL. If this option is set to negate, pdnsd will immediately return
the answer NXDOMAIN (unknown domain) without querying additional servers. The fail
setting is useful if you don't always trust the servers in this section, but do
trust the servers in the following section. The negate setting can be used to
completely censor certain IP addresses. In this case you should put the same reject
list in every server section, and also set the reject_recursively option (see
below) to true.
The default is fail.
reject_recursively=(on|off);
New in version 1.2.6: Normally pdnsd checks for addresses in the reject list (see
above) only when the reply comes directly from a name server listed in the
configuration file. With this option set to on, pdnsd will also do this check for
name servers that where obtained from NS records in the authority section of a
previous reply (which was incomplete and non-authoritative).
Default is off.
policy=(included|excluded|simple_only|fqdn_only);
pdnsd supports inclusion/exclusion lists for server sections: with include= and
exclude= (see below) you can specify domain names for which this server will be
used or will not be used. The first match counts (i.e., the first include or
exclude rule in a server section that matches a domain name is applied, and the
search for other rules is terminated). If no rule matched a given domain name, the
policy= option determines whether this server is used for the lookup for that
domain name; when included is given, the server will be asked, and when excluded is
given, it will not. If simple_only is given the server will be used if the name to
lookup is a simple (single-label) domain name, on the other hand if fqdn_only is
given the server will be used only for names consisting of two or more labels
(i.e. the name has at least one dot in-between).
If no server is available for a queried domain, pdnsd will return an error message
to the client that usually will stop the client's attempts to resolve a specific
domain from this server (the libc resolver will e.g. return an error to the
application that tried to resolve the domain if no other servers are available in
the resolv.conf). This may be of use sometimes.
Note: the simple_only and fqdn_only constants were added by Paul Rombouts. They
are useful for controlling which name servers (if any) will be used by pdnsd for
resolving simple (single-label) host names. fqdn_only used to stand for "fully
qualified domain name only", but this is actually a misnomer. The names in queries
received by pdnsd are always considered to be fully qualified. If you do not
exactly understand what the options simple_only and fqdn_only are good for, you are
probably better off not using them.
The default for this option is included.
include=string;
This option adds an entry to the exclusion/inclusion list. If a domain matches the
name given as string, the server is queried if this was the first matching rule
(see also the entry for policy).
If the given name starts with a dot, the whole subdomain of the given name
including the one of that name is matched, e.g. ".foo.bar." will match the domain
names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case, of
course) will be matched (hint: if you want to include all subdomains, but not the
domain of the given name itself, place an exact-match exclude rule before the
include rule, e.g: exclude="foo.bar."; include=".foo.bar.";
Previous versions of pdnsd required that names given with this and the next option
ended in a dot, but since version 1.1.8b1-par8, pdnsd automatically adds a dot at
the end if it is missing.
pdnsd now also accepts a more compact notation for adding several "include" entries
in one line, e.g.:
include=".foo",".bar",".my.dom";
exclude=string;
This option adds an entry to the exclusion/inclusion list. If a domain matches the
name given as string, the server is not queried if this was the first matching rule
(see also the entry for policy).
If the given name starts with a dot, the whole subdomain of the given name
including the one of that name is matched, e.g. ".foo.bar." will match the domain
names a.foo.bar., a.b.c.foo.bar. and foo.bar.
If it does not start in a dot, only exactly the given name (ignoring the case, of
course) will be matched (hint: if you want to exclude all subdomains, but not the
domain of the given name itself, place an exact-match include rule before the
exclude rule, e.g: include="foo.bar."; exclude=".foo.bar.";
pdnsd now also accepts a more compact notation for adding several "exclude" entries
in one line, e.g.:
exclude=".foo",".bar",".my.dom";
rr Section
Every rr section specifies a dns resource record that is stored locally. It allows you to
specify own dns records that are served by pdnsd in a limited way. Only A, PTR, CNAME,
MX, NS and SOA records are implemented.
This option is intended to allow you to define RRs for 1.0.0.127.in-addr.arpa. and
localhost. (and perhaps even one or two hosts) without having to start an extra named if
your cached name servers do not serve those records. It is NOT intended and not capable
to work as a full-featured name server.
name=string;
Specifies the name of the resource records, i.e. the domain name of the resource
the record describes. This option must be specified before any a, ptr, cname, mx,
ns or soa records. Names are interpreted as absolute domain names (i.e. pdnsd
assumes they end in the root domain). For this and all following arguments that
take domain names, you need to specify domain names in dotted notation (example
venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the configuration
file ended in a dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
dot at the end if it is missing.
New in version 1.2: It is also possible to specify a name starting with the label
*. Such a name is called a wildcard. The * in a wildcard can match one or more
labels in a queried name, but only whole labels. Any other * characters in a
wildcard, apart from the leading one, will only match a literal *.
For example, *.mydomain will match a.mydomain or www.a.mydomain, but not mydomain.
*.a*.mydomain will match www.a*.mydomain, but not www.ab.mydomain. *a.mydomain
will only match itself.
Before you can specify an rr section with name=*.mydomain you must define some
records for mydomain, typically NS and/or SOA records. Example:
rr {
name = mydomain;
ns = localhost;
soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
}
rr {
name = *.mydomain;
a = 192.168.1.10;
}
In this example, www.mydomain and ftp.mydomain will resolve to the numeric address
192.168.1.10 (unless you add rr sections explicitly specifying different addresses
for www.mydomain or ftp.mydomain). If you want mydomain also to resolve to a
numeric address, add an A record to the first rr section.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local records for this rr
section. This means that pdnsd flags the domain record so that records of this
domain that are not present in the cache are treated as non-existent, i.e. no other
servers are queried for that record type, and an response containing none of those
records is returned. This is most time what people want: if you add an A record for
a host, and it has no AAAA record (thus no IPv6 address), you normally don't want
other name servers to be queried for it.
This is on by default.
Please note that this only has an effect if it precedes the name option!
reverse=(on|off);
New in version 1.2: If you want a locally defined name to resolve to a numeric
address and vice versa, you can achieve this by setting reverse=on before defining
the A record (see below). The alternative is to define a separate PTR record, but
you will probably find this option much more convenient.
The default is off.
a=string;
Defines an A (host address) record. The argument is an IPv4 address in dotted
notation. pdnsd will serve this address for the host name given in the name
option.
Provided there is sufficient support in the C libraries and support for AAAA
records was not disabled, the argument string may also be an IPv6 address, in which
case an AAAA record will be defined.
This option be may used multiple times within an rr section, causing multiple
addresses to be defined for the name. However, if you put the different addresses
in different rr sections for the same name, the definition in the last rr section
will cancel the definitions in the previous ones.
ptr=string;
Defines a PTR (domain name pointer) record. The argument is a host name in dotted
notation (see name). The ptr record is for resolving addresses into names. For
example, if you want the address 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 address written as number constitutes a sub-domain under the
domain in-addr.arpa.
So, if you want to compose an address for reverse resolving, take your ip in dotted
notation (e.g. 1.2.3.4), reverse the byte order (4.3.2.1) and append in-addr.arpa.
(4.3.2.1.in-addr.arpa.) Then, define an rr section giving this address as name and
the domain name corresponding to that ip in the ptr option.
cname=string;
Defines a CNAME (canonical name) record. The argument should be a fully-qualified
host name in dotted notation (see name). A CNAME is the DNS equivalent of an alias
or symbolic link.
A useful application for CNAMEs is giving short, easy to remember nicknames to
hosts with complicated names. For example, you might want the name "news" to refer
to your ISP's news server "nntp2.myisp.com". Instead of adding an A record for
"news" with the same address as "nntp2.myisp.com", you could put in a CNAME
pointing to "nntp2.myisp.com", so that if the IP address of the news server
changes, there is no need to update the record for "news".
To implement this with pdnsd, you could add the following section to your
configuration file:
rr {
name = news;
cname = nntp2.myisp.com;
owner = localhost;
}
mx=string,number;
Defines an MX (mail exchange) record. The string is the host name of the mail
server in dotted notation (see name). The number specifies the preference level.
When you send mail to someone, your mail typically goes from your E-mail client to
an SMTP server. The SMTP server then checks for the MX record of the domain in the
E-mail address. For example, with joe@example.com, it would look for the MX record
for example.com and find that the name of mail server for that domain is, say,
mail.example.com. The SMTP server then gets the A record for mail.example.com, and
connects to the mail server.
If there are multiple MX records, the SMTP server will pick one based on the
preference level (starting with the lowest preference number, working its way up).
Don't define MX records with pdnsd unless you know what you're doing.
owner=string;
or
ns=string;
Defines an NS (name server) record. Specifies the name of the host which should be
authoritative for the records you defined in the rr section. This is typically the
host pdnsd runs on.
Note: In previous versions of pdnsd this option had to be specified before any a,
ptr, cname, mx or soa entries. In version 1.2, the restrictions on this option are
same as the options just mentioned, and it must listed after the name= option.
This can be a pain if you want to use an old config file which specifies owner=
before name= (sorry about that). Apart from greater consistency, the advantage is
that you can now specify as many NS records as you like (including zero).
soa=string,string,number,timespec,timespec,timespec,timespec;
This defines a soa (start of authority) record. The first string is the domain name
of the server and should be equal to the name you specified as owner.
The second string specifies the email address of the maintainer of the name server.
It is also specified as a domain name, so you will have to replace the @ sign in
the name with a dot (.) to get the name you have to specify here. The next
parameter (the first number) is the serial number of the record. You should
increment this number if you change the record.
The 4th parameter is the refresh timeout. It specifies after what amount of time a
caching server should attempt to refresh the cached record.
The 5th parameter specifies a time after which a caching server should attempt to
refresh the record after a refresh failure.
The 6th parameter defines the timeout after which a cached record expires if it has
not been refreshed.
The 7th parameter is the ttl that is specified in every rr and should be the same
as given with the ttl option (if you do not specify a ttl, use the default 86400).
txt=string,...,string;
New in version 1.2.9: Defines an TXT record. You can specify one or more strings
here.
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 explicitly
invalidated or deleted by the user using pdnsd-ctl.
This is useful if a certain application asks periodically for nonexisting hosts or RR
types and you do not want a query to go out every time the cached record has timed out.
Example: Netscape Communicator will ask for the servers news and mail on startup if
unconfigured. If you do not have a dns search list for your network, you can inhibit
outgoing queries for these by specifying
neg {
name = news;
types = domain;
}
neg {
name = mail;
types = domain;
}
in your config file. If you have a search list, you have to repeat that for any entry in
your search list in addition to the entries given above!
In versions 1.1.11 and later, if you negate whole domains this way, all subdomains will be
negated as well. Thus if you specify
neg {name=example.com; types=domain;} in the config file, this will also negate
www.example.com, xxx.adserver.example.com, etc.
name=string;
Specifies the name of the domain for which negative cache entries are created.
This option must be specified before the types option. Names are interpreted as
absolute domain names (i.e. pdnsd assumes they end in the root domain). You need
to specify domain names in dotted notation (example venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the configuration
file ended in a dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
dot at the end if it is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
types=(domain|rr_type[,rr_type[,rr_type[,...]]]);
Specifies what is to be cached negatively: domain will cache the whole domain
negatively; alternatively, you can specify a comma-separated list of RR types which
are to be cached negatively. You may specify multiple types options, but domain and
the RR types are mutually exclusive.
The RR types are specified using their official names from the RFC's in capitals,
e.g. A, CNAME, NS, PTR, MX, AAAA, ...
The command pdnsd-ctl list-rrtypes will give you a complete list of those types.
pdnsd-ctl is built along with pdnsd and will be installed in the same directory as
the pdnsd binary during make install.
source Section
Every source section allows you to let pdnsd read the records from a file in an
/etc/hosts-like format. pdnsd will generate records to resolve the entries address from
its host name and vice versa for every entry in the file. This is normally easier than
defining an rr for every of your addresses, since localhost and your other FQDNs are
normally given in /etc/hosts.
The accepted format is as follows: The #-sign initiates a comment, the rest of the line
from the first occurence of this character on is ignored. Empty lines are tolerated.
The first entry on a line (predeceded by an arbitrary number of tabs and spaces) is the IP
in dotted notation, the second entry on one line (separated by the first by an arbitrary
number of tabs and spaces) is the FQDN (fully qualified domain name) for that ip. The rest
of the line is ignored by default (in the original /etc/hosts, it may contain information
not needed by pdnsd).
owner=string;
Specifies the name of the host pdnsd runs on and that are specified in dns answers
(specifically, nameserver records). Must be specified before any file entries.
Names are interpreted as absolute domain names (i.e. pdnsd assumes they end in the
root domain). You need to specify domain names in dotted notation (example
venera.isi.edu.).
Previous versions of pdnsd required that domain names given in the configuration
file ended in a dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
dot at the end if it is missing.
ttl=timespec;
Specifies the ttl (time to live) for all resource records in this section after
this entry. This may be redefined. The default is 86400 seconds (=1 day).
file=string;
The string specifies a file name. For every file entry in a source section, pdnsd
will try to load the given file as described above. Failure is indicated only when
the file cannot be opened, malformed entries will be ignored.
serve_aliases=(on|off);
If this is turned on pdnsd will serve the aliases given in a hosts-style file.
These are the third entry in a line of a hosts-style file, which usually give a
"short name" for the host. This may be used to support broken clients without a
proper domain-search option. If no aliases are given in a line of the file, pdnsd
behaves as without this option for this line.
This feature was suggested by Bert Frederiks.
It is off by default.
authrec=(on|off);
If this is turned on, pdnsd will create authoritative local records with the data
from the hosts file. Please see the description of the option of the same name in
the rr section for a closer description of what this means. Please note that this
only has an effect for files sourced with file options subsequent to this option.
This is on by default.
include Section
A configuration file may include other configuration files. However, only the top-level
configuration file may contain global and server sections, thus include files are
effectively limited to sections that add local definitions to the cache.
Include sections currently only have one type of option, which may be given multiple times
within a single section.
file=string;
The string specifies a file name. For every file option in an include section,
pdnsd will parse the given file as described above. The file may contain include
sections itself, but as a precaution pdnsd checks that a certain maximum depth is
not exceeded to guard against the possibility of infinite recursion.
VERSION
This man page is correct for version 1.2.9a-par of pdnsd.
SEE ALSO
pdnsd(8), pdnsd-ctl(8)
More documentation is available in the doc/ subdirectory of the source, or in
/usr/share/doc/pdnsd/ if you are using a binary package.
AUTHORS
pdnsd was originally written by Thomas Moestl <tmoestl@gmx.net> ⟨⟩ and was extensively
revised by Paul A. Rombouts <p.a.rombouts@home.nl> ⟨⟩ (for versions 1.1.8b1-par and
later).
Several others have contributed to pdnsd; see files in the source or /usr/share/doc/pdnsd/
directory.
This man page was automatically generated from the html documentation for pdnsd, using a
customized Perl script written by Paul A. Rombouts.
Last revised: 27 February 2012 by Paul A. Rombouts