1329 lines
62 KiB
Groff
1329 lines
62 KiB
Groff
.\" Generated automatically from the html documentation by html2confman.pl
|
|
.\"
|
|
.\" Manpage for pdnsd.conf (pdnsd configuration file)
|
|
.\"
|
|
.\" Copyright (C) 2000, 2001 Thomas Moestl
|
|
.\" Copyright (C) 2003, 2004, 2005, 2006, 2007 Paul A. Rombouts
|
|
.\"
|
|
.\" This manual is a part of the pdnsd package, and may be distributed in
|
|
.\" original or modified form under terms of the GNU General Public
|
|
.\" License, as published by the Free Software Foundation; either version
|
|
.\" 3, or (at your option) any later version.
|
|
.\" You can find a copy of the GNU GPL in the file COPYING in the source
|
|
.\" or documentation directory.
|
|
.\"
|
|
.TH PDNSD.CONF 5 "Apr 2012" "pdnsd @fullversion@"
|
|
.SH NAME
|
|
pdnsd.conf \- The configuration file for pdnsd
|
|
.hw config
|
|
.SH DESCRIPTION
|
|
.PP
|
|
This manual page describes the layout of the
|
|
.BR pdnsd (8)
|
|
configuration file and the available configuration options.
|
|
The default location of the file is @sysconfdir@/pdnsd.conf. This may be changed
|
|
with the \fB-c\fP command line option.
|
|
An example pdnsd.conf comes with the pdnsd distribution in the documentation directory
|
|
or in @sysconfdir@/pdnsd.conf.sample.
|
|
.SH "FILE FORMAT"
|
|
.PP
|
|
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
|
|
|
|
\fIoption_name\fP=\fIoption_value\fP;
|
|
|
|
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.
|
|
.br
|
|
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.
|
|
.br
|
|
Some options take more than one value; in this case, the values are separated with commas.
|
|
.br
|
|
If you may supply one of a set of possible values to an option, this is noted
|
|
in the documentation as
|
|
(option1|option2|option3|...)
|
|
.br
|
|
The constants true|false and yes|no
|
|
are accepted as synonyms for the constants on|off.
|
|
.br
|
|
Comments may be enclosed in /* and */, nested comments are possible. If the
|
|
# sign or two slashes (//) appear in the configuration file, everything from
|
|
these signs to the end of the current line is regarded as a comment and ignored.
|
|
.br
|
|
There are examples for nearly all options in the sample config file.
|
|
|
|
.SS 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.
|
|
.br
|
|
These are the possible options:
|
|
|
|
.TP
|
|
.B perm_cache=(\fInumber\fP|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.
|
|
.TP
|
|
.B cache_dir=\fIstring\fP;
|
|
Set the directory you want to keep the cache in.
|
|
The default is "@cachedir@"
|
|
(unless pdnsd was compiled with a different default).
|
|
.TP
|
|
.B server_port=\fInumber\fP;
|
|
Set the server port. This is especially useful when you want to start the
|
|
server and are not root. Note that you may also not specify uptest=ping in
|
|
the server section as non-root.
|
|
.br
|
|
The default port is 53, the RFC-standard one. Note that you should only use
|
|
non-standard ports when you only need clients on your machine to communicate
|
|
with the server; others will probably fail if the try to contact the server
|
|
on the basis of an NS record, since the A record that supplies the address for
|
|
(among others) name servers does not have a port number specification.
|
|
.TP
|
|
.B server_ip=\fIstring\fP;
|
|
or
|
|
.PD 0
|
|
.TP
|
|
.PD
|
|
.B interface=\fIstring\fP;
|
|
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.
|
|
.br
|
|
The IP address used to need quotation marks around it, but since version 1.1.10
|
|
this is no longer necessary.
|
|
.br
|
|
If pdnsd has been compiled with both IPv4 and IPv6 support, and you want to
|
|
specify an IPv6 address here, then unless pdnsd was compiled to start up in IPv6 mode
|
|
by default, you will need to use the \-6 command-line option or
|
|
set run_ipv4=off first (see below) in order to ensure that the
|
|
IPv6 address is parsed correctly.
|
|
.br
|
|
If pdnsd is running in IPv6 mode and you specify an IPv4 address here,
|
|
it will automatically be mapped to an IPv6 address.
|
|
.br
|
|
\fINew in version 1.2:\fP 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.
|
|
.TP
|
|
.B outgoing_ip=\fIstring\fP;
|
|
or
|
|
.PD 0
|
|
.TP
|
|
.PD
|
|
.B outside_interface=\fIstring\fP;
|
|
\fINew in version 1.2.9:\fP
|
|
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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B max_ttl=\fItimespec\fP;
|
|
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).
|
|
.TP
|
|
.B min_ttl=\fItimespec\fP;
|
|
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.
|
|
.TP
|
|
.B neg_ttl=\fItimespec\fP;
|
|
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.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
\fINew in version 1.2.8:\fP 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.
|
|
.br
|
|
The preset is "default" (used to be auth).
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
The default is auth.
|
|
.TP
|
|
.B run_as=\fIstring\fP;
|
|
This option allows you to let pdnsd change its user and group id after operations that needed
|
|
privileges have been done. This helps minimize security risks and is therefore recommended. The
|
|
supplied string gives a user name whose user id and primary group id are taken.
|
|
.br
|
|
A little more details: after reading the config file, becoming a daemon (if specified) and starting
|
|
the server status thread, the main thread changes its gid and uid, as do all newly created threads
|
|
thereafter. By taking another uid and gid, those threads run with the privileges of the
|
|
specified user.
|
|
Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option
|
|
is set to 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.
|
|
.br
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
This option is on by default.
|
|
.br
|
|
Note that this option has no effect on Non-Linux systems.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
The penalty is a possible performance decrease, in particular, more queries might be necessary for the same
|
|
operation.
|
|
.br
|
|
You should also notice that there may be other similar security problems, which are essentially problems of
|
|
the DNS, i.e.
|
|
any "traditional" server has them (the DNS security extensions solve these problems, but are not widely
|
|
supported).
|
|
One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a
|
|
query
|
|
you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet
|
|
count of 32768 is needed for that attack). pdnsd can use TCP for queries,
|
|
which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd
|
|
chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network
|
|
traffic, this attack is relatively easy, though.
|
|
.br
|
|
This vulnerability is not pdnsd's fault, and is possible using any conventional
|
|
name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP).
|
|
.br
|
|
The paranoid option is off by default.
|
|
.br
|
|
.TP
|
|
.B ignore_cd=(on|off);
|
|
\fINew in version 1.2.8:\fP This option lets you specify that the CD bit of a DNS query will be ignored.
|
|
Otherwise pdnsd will reply FORMERR to clients that set this bit in a query.
|
|
It is safe to enable this option, as the CD bit refers to 'Checking Disabled'
|
|
which means that the client will accept non-authenticated data.
|
|
.br
|
|
This option is on by default. Turn it off if you want the old behaviour (before version 1.2.8).
|
|
.TP
|
|
.B scheme_file=\fIstring\fP;
|
|
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.
|
|
.TP
|
|
.B status_ctl=(on|off);
|
|
This has the same effect as the \-s command line option: the status control is enabled when
|
|
on is specified.
|
|
.br
|
|
\fIAdded by Paul Rombouts\fP: 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.
|
|
.TP
|
|
.B daemon=(on|off);
|
|
This has the same effect as the \-d command line option: the daemon mode is enabled when
|
|
on is specified.
|
|
.br
|
|
Default is off.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
Default is on.
|
|
.TP
|
|
.B pid_file=\fIstring\fP;
|
|
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.
|
|
.TP
|
|
.B verbosity=\fInumber\fP;
|
|
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).
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B debug=(on|off);
|
|
This has the same effect as the \-g command line option: the debugging messages are enabled when
|
|
on is specified.
|
|
.TP
|
|
.B ctl_perms=\fInumber\fP;
|
|
This option allows you to set the file permissions that the pdnsd status control socket will have. These
|
|
are the same as file permissions. The owner of the file will be the run_as user, or, if none is specified,
|
|
the user who started pdnsd. If you want to specify the permissions in octal (as usual), don't forget
|
|
the leading zero (0600 instead of 600!). To use the status control, write access is needed. The default
|
|
is 0600 (only the owner may read or write).
|
|
.br
|
|
Please note that the socket is kept in the cache directory, and that the cache directory permissions
|
|
might also need to be adjusted. Please ensure that the cache directory is not writeable for untrusted
|
|
users.
|
|
.TP
|
|
.B proc_limit=\fInumber\fP;
|
|
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.
|
|
.br
|
|
The default for this option is 40.
|
|
.TP
|
|
.B procq_limit=\fInumber\fP;
|
|
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.
|
|
.br
|
|
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).
|
|
.br
|
|
The default for this option is 60.
|
|
.TP
|
|
.B tcp_qtimeout=\fItimespec\fP;
|
|
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.
|
|
.TP
|
|
.B par_queries=\fInumber\fP;
|
|
This option used to set the maximum number of remote servers that would be queried simultaneously,
|
|
for every query that pdnsd receives.
|
|
.br
|
|
Since version 1.1.11, the meaning of this option has changed slightly.
|
|
It is now the increment with which the number of parallel queries is
|
|
increased when the previous set of servers has timed out.
|
|
For example, if we have a list \fIserver1, server2, server3,\fP etc. of available servers
|
|
and par_queries=2, then pdnsd will first send queries to \fIserver1\fP and \fIserver2\fP,
|
|
and listen for responses from these servers.
|
|
.br
|
|
If these servers do not send a reply within their timeout period, pdnsd will send additional
|
|
queries to \fIserver3\fP and \fIserver4\fP, and listen for responses from
|
|
\fIserver1, server2, server3\fP and \fIserver4\fP, and so on until a useful reply is
|
|
received or the list is exhausted.
|
|
.br
|
|
In the worst case there will be pending queries to all the servers in the list of available servers.
|
|
We may be using more system resources this way (but only if the first servers in the list
|
|
are slow or unresponsive), but the advantage is that we have a greater chance of catching a reply.
|
|
After all, if we wait longer anyway, why not for more servers.
|
|
.br
|
|
See also the explanation of the global timeout option below.
|
|
.br
|
|
1 or 2 are good values for this option.
|
|
The default is set at compile time using the \-\-with\-par\-queries option to configure.
|
|
.TP
|
|
.B timeout=\fItimespec\fP;
|
|
This is the global timeout parameter for dns queries.
|
|
This specifies the minimum period of time pdnsd will wait after sending the
|
|
first query to a remote server before giving up without having
|
|
received a reply. The timeout options in the configuration file are
|
|
now only minimum timeout intervals. Setting the global timeout option
|
|
makes it possible to specify quite short timeout intervals in the
|
|
server sections (see below). This will have the effect that pdnsd will start
|
|
querying additional servers fairly quickly if the first servers are
|
|
slow to respond (but will still continue to listen for responses from
|
|
the first ones). This may allow pdnsd to get an answer more quickly in
|
|
certain situations.
|
|
.br
|
|
If you use 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.
|
|
.br
|
|
Default value is 0.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
On by default.
|
|
.TP
|
|
.B query_port_start=(\fInumber\fP|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.
|
|
.br
|
|
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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B query_port_end=\fInumber\fP;
|
|
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.
|
|
.TP
|
|
.B delegation_only=\fIstring\fP;
|
|
\fIAdded by Paul Rombouts\fP: 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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B ipv4_6_prefix=\fIstring\fP;
|
|
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.
|
|
.br
|
|
The default is "::ffff.0.0.0.0".
|
|
.TP
|
|
.B 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).
|
|
.br
|
|
This option was contributed by Jan-Marek Glogowski.
|
|
.br
|
|
On by default.
|
|
.TP
|
|
.B udpbufsize=\fInumber\fP;
|
|
\fINew in version 1.2.9:\fP
|
|
This option sets the upper limit on the size of UDP DNS messages. The default is 1024.
|
|
.br
|
|
See also the edns_query server option below.
|
|
|
|
.SS 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.
|
|
.br
|
|
You probably want to specify the dns server in your LAN, the caching dns servers
|
|
of your internet provider or even a list of root servers in one or more server sections.
|
|
.br
|
|
The supported options in this section are:
|
|
|
|
.TP
|
|
.B label=\fIstring\fP;
|
|
Specify a label for the server section. This can be used to refer to this section
|
|
when using pdnsd\-ctl, the pdnsd control utility.
|
|
.br
|
|
You can give several server sections the same label, but if you want to change the addresses
|
|
of a server section (see \fBip\fP option below) during run-time with
|
|
"pdnsd\-ctl\ server\ \fIlabel\fP\ up\ \fIdns1\fP,\fIdns2\fP,...",
|
|
the label must be unique.
|
|
.TP
|
|
.B ip=\fIstring\fP;
|
|
Give the IP (the address, \fInot\fP the host name) of the server.
|
|
.br
|
|
Multiple IP addresses can be given per server section.
|
|
This can be done by entering multiple lines of the form ip=\fIstring\fP;
|
|
or a single line like this:
|
|
|
|
ip=\fIstring\fP,\fIstring\fP,\fIstring\fP;
|
|
|
|
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.
|
|
.br
|
|
If pdnsd has been compiled with both IPv4 and IPv6 support, any IPv6 addresses you specify
|
|
here will be skipped with a warning message, unless pdnsd is running in IPv6 mode.
|
|
Thus, unless pdnsd was compiled to startup in IPv6 mode by default, you need to use the
|
|
command-line option \-6 or set run_ipv4=off
|
|
first (see global section) in order to ensure
|
|
that IPv6 addresses are parsed correctly.
|
|
.br
|
|
If pdnsd is running in IPv6 mode and you specify an IPv4 address here,
|
|
it will automatically be mapped to an IPv6 address.
|
|
.TP
|
|
.B file=\fIstring\fP;
|
|
\fINew in version 1.2:\fP 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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B port=\fInumber\fP;
|
|
Give the port the remote name server listens on. Default is 53 (the official
|
|
dns port)
|
|
.TP
|
|
.B uptest=(ping|none|if|dev|diald|exec|query);
|
|
Determine the method to check whether the server is available. Currently
|
|
defined methods are:
|
|
.IP
|
|
\(bu \fBping\fP: 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.
|
|
.IP
|
|
\(bu \fBnone\fP: The availability status is not changed, only the time stamp is updated.
|
|
.IP
|
|
\(bu \fBif\fP: 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.
|
|
.IP
|
|
\(bu \fBdev\fP and \fBdiald\fP: Perform an if uptest, and, if that
|
|
was succesful, additionally check whether a program is running that
|
|
has locked a given (modem-) device. The needed parameters are an interface (specified as for the if
|
|
uptest, e.g. "ppp0") and a device relative to /dev (e.g.
|
|
"modem" for /dev/modem specified using the device= option.
|
|
pdnsd will then look for a pid file for the given interface in /var/lock (e.g.
|
|
/var/run/ppp0.pid) and for a lockfile for the given device (e.g. /var/lock/LCK..modem),
|
|
and then test whether the locking process is the process that created the pid file and this process is still
|
|
alive. If this is the case, the normal if uptest is executed for the given interface.
|
|
.br
|
|
The dev option is for pppd dial-on-demand, diald is the same for diald users.
|
|
.IP
|
|
\(bu \fBexec\fP: 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.
|
|
.IP
|
|
\(bu \fBquery\fP: \fINew in version 1.2:\fP
|
|
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 \fBnone\fP.
|
|
|
|
\fBNOTE\fP: 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!
|
|
.TP
|
|
.B ping_timeout=\fInumber\fP;
|
|
Sets the timeout for the ping test in tenths of seconds
|
|
(this unit is used for legacy reasons; actually the current implementation is
|
|
only accurate to a second).
|
|
.br
|
|
The default is 600 (one minute).
|
|
.TP
|
|
.B ping_ip=\fIstring\fP;
|
|
The IP address for the ping test. The default is the IP of the name server.
|
|
.TP
|
|
.B query_test_name=\fIstring\fP;
|
|
\fINew in version 1.2.9:\fP
|
|
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.
|
|
.br
|
|
If the the remote server ignores empty queries, you will probably want to set
|
|
query_test_name="." (the root domain).
|
|
.TP
|
|
.B uptest_cmd=\fIstring\fP,\fIstring\fP;
|
|
or
|
|
.PD 0
|
|
.TP
|
|
.PD
|
|
.B uptest_cmd=\fIstring\fP;
|
|
Sets the command for the uptest=exec function to the first string.
|
|
If the second string is given, it specifies a user with whose user
|
|
id and primary group id the command is executed.
|
|
.br
|
|
This is especially useful if you are executing the server as root,
|
|
but do not want the uptest to be performed with root privileges.
|
|
In fact, you should never execute the uptest as root if you can help
|
|
it.
|
|
.br
|
|
If the server is running setuid or setgid, the privileges thus gained
|
|
are attempted to be dropped even before changing identity to the
|
|
specified user to prevent setuid/gid security holes (otherwise, any
|
|
user might execute commands as root if you setuid the executable).
|
|
.br
|
|
\fBNote that this is not always possible, and that pdnsd should never
|
|
be installed as setuid or setgid.\fP
|
|
The command is executed using /bin/sh, so you should be able to use
|
|
shell builtin commands.
|
|
.TP
|
|
.B interval=(\fItimespec\fP|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.
|
|
.br
|
|
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 ;\-)
|
|
.br
|
|
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.
|
|
.br
|
|
\fINew in version 1.2.3:\fP
|
|
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.
|
|
.TP
|
|
.B interface=\fIstring\fP;
|
|
The network interface (or network device, e.g. "eth0") for the uptest=if option.
|
|
Must be specified if uptest=if is given.
|
|
.TP
|
|
.B device=\fIstring\fP;
|
|
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.
|
|
.br
|
|
Must be specified if uptest=dev is given.
|
|
.TP
|
|
.B timeout=\fItimespec\fP;
|
|
Set the timeout for the dns query. The default is 120 seconds. You probably want to set this lower.
|
|
.br
|
|
Timeouts specified in the configuration file are only treated as the
|
|
minimum period of time to wait for a reply. A queries to a remote
|
|
server are not canceled until a useful reply has been received, or all
|
|
the other queries have timed out or failed.
|
|
.br
|
|
If you have also set the global timeout option, you may consider setting a fairly small value here.
|
|
See the explanation of the timeout option in the global
|
|
section for what that means.
|
|
.TP
|
|
.B purge_cache=(on|off);
|
|
In every fetched dns record, there is a cache timeout given, which
|
|
specifies how long the fetched data may be cached until it needs to be
|
|
reloaded. If purge_cache is set to off, the stale records are not purged
|
|
(unless the cache size would be exceeded, in this case the oldest records are purged).
|
|
Instead, they are still served if they cannot succesfully be
|
|
updated (e.g. because all servers are down).
|
|
.br
|
|
Default is off.
|
|
.TP
|
|
.B caching=(on|off);
|
|
Specifies if caching shall be performed for this server at all. Default is
|
|
on.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
Some buggy name servers may not deliver CNAME records when not asked for
|
|
all records. I do not know if such servers are around, but if you have
|
|
trouble resolving certain host names, try turning this option off.
|
|
.br
|
|
A last note: If you use multiple pdnsd's that access each other, turning
|
|
this option on is probably a big win.
|
|
.br
|
|
This on by default.
|
|
.TP
|
|
.B edns_query=(on|off);
|
|
\fINew in version 1.2.9:\fP
|
|
Specifies whether to use EDNS (Extension mechanisms for DNS) for outgoing queries.
|
|
Currently this is only useful for allowing UDP message sizes larger than 512 bytes.
|
|
Note that setting this option on can give problems in combination with some legacy
|
|
systems or software, including, embarrassingly enough, previous versions of pdnsd.
|
|
.br
|
|
The default is off, but if your network can handle UDP payloads
|
|
significantly larger than 512 bytes, the recommended value is on.
|
|
.br
|
|
Note that this option only effects outgoing queries. If pdnsd receives a query using
|
|
EDNS, it will reply using EDNS regardless of the value of this option.
|
|
|
|
See also the udpbufsize option above.
|
|
.TP
|
|
.B scheme=\fIstring\fP;
|
|
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.
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B 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).
|
|
.br
|
|
This option is useful when you do not want pdnsd to make connections to outside servers
|
|
for some reasons (e.g. when a firewall is blocking such queries).
|
|
.br
|
|
I recommend that you turn on lean_query when using this option.
|
|
.br
|
|
Default is off.
|
|
.TP
|
|
.B 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".
|
|
.br
|
|
This option is also necessary if you use the delegation_only option.
|
|
.br
|
|
\fINew in version 1.2.8:\fP 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.
|
|
.br
|
|
Default is off.
|
|
.TP
|
|
.B randomize_servers=(on|off);
|
|
\fINew in version 1.2.6:\fP 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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B reject=\fIstring\fP;
|
|
\fINew in version 1.2.6:\fP This option can be used to make pdnsd reject replies that
|
|
contain certain IP addresses. You can specify a single IP address, which will be matched
|
|
exactly, or a range of addresses using an address/mask pair.
|
|
The mask can be specified as a simple integer, indicating the number of initial 1 bits in
|
|
the mask, or in the usual IP address notation. IP addresses may be either IPv4 or IPv6
|
|
(provided there is sufficient support in the C libraries and support for AAAA records was
|
|
not disabled).
|
|
When addresses in the reject list are compared with those in a reply, only the bits
|
|
corresponding to those set in the netmask are significant, the rest are ignored.
|
|
.br
|
|
Multiple addresses or address/mask pairs may be specified; this can be done by entering
|
|
multiple lines of the form reject=\fIstring\fP;
|
|
or a single line like this:
|
|
|
|
reject=\fIstring\fP,\fIstring\fP,\fIstring\fP;
|
|
|
|
How pdnsd reacts when an address in the reply matches one in the reject list,
|
|
depends on the reject_policy option, see below.
|
|
.TP
|
|
.B reject_policy=(fail|negate);
|
|
\fINew in version 1.2.6:\fP
|
|
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.
|
|
.br
|
|
The default is fail.
|
|
.TP
|
|
.B reject_recursively=(on|off);
|
|
\fINew in version 1.2.6:\fP 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).
|
|
.br
|
|
Default is off.
|
|
.TP
|
|
.B 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).
|
|
.br
|
|
If no server is available for a queried domain, pdnsd will return an error message
|
|
to the client that usually will stop the client's attempts to resolve a specific
|
|
domain from this server (the libc resolver will e.g. return an error to the application that
|
|
tried to resolve the domain if no other servers are available in the resolv.conf).
|
|
This may be of use sometimes.
|
|
.br
|
|
\fINote\fP: 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.
|
|
.br
|
|
The default for this option is included.
|
|
.TP
|
|
.B include=\fIstring\fP;
|
|
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).
|
|
.br
|
|
If the given name starts with a dot, the whole subdomain
|
|
of the given name including the one of that name is matched, e.g. ".foo.bar."
|
|
will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
|
|
.br
|
|
If it does not start in a dot, only exactly the given name (ignoring the case, of course)
|
|
will be matched (hint: if you want to include all subdomains, but not the domain of the given
|
|
name itself, place an exact-match exclude rule before the include rule, e.g:
|
|
exclude="foo.bar."; include=".foo.bar.";
|
|
.br
|
|
Previous versions of pdnsd
|
|
required that names given with this and the next option ended in a dot, but since
|
|
version 1.1.8b1-par8, pdnsd automatically adds a dot at the end if it
|
|
is missing.
|
|
.br
|
|
pdnsd now also accepts a more compact notation for adding several "include" entries in
|
|
one line, e.g.:
|
|
|
|
include=".foo",".bar",".my.dom";
|
|
|
|
.TP
|
|
.B exclude=\fIstring\fP;
|
|
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).
|
|
.br
|
|
If the given name starts with a dot, the whole subdomain
|
|
of the given name including the one of that name is matched, e.g. ".foo.bar."
|
|
will match the domain names a.foo.bar., a.b.c.foo.bar. and foo.bar.
|
|
.br
|
|
If it does not start in a dot, only exactly the given name (ignoring the case, of course)
|
|
will be matched (hint: if you want to exclude all subdomains, but not the domain of the given
|
|
name itself, place an exact-match include rule before the exclude rule, e.g:
|
|
include="foo.bar."; exclude=".foo.bar.";
|
|
.br
|
|
pdnsd now also accepts a more compact notation for adding several "exclude" entries in
|
|
one line, e.g.:
|
|
|
|
exclude=".foo",".bar",".my.dom";
|
|
|
|
|
|
.SS 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.
|
|
.br
|
|
This option is intended to allow you to define RRs for 1.0.0.127.in-addr.arpa.
|
|
and localhost. (and perhaps even one or two hosts) without having to start an
|
|
extra named if your cached name servers do not serve those records.
|
|
It is \fBNOT\fP intended and not capable to work as a full-featured name server.
|
|
|
|
.TP
|
|
.B name=\fIstring\fP;
|
|
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.).
|
|
.br
|
|
Previous versions of pdnsd
|
|
required that domain names given in the configuration file ended in a
|
|
dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
|
|
dot at the end if it is missing.
|
|
.br
|
|
\fINew in version 1.2:\fP It is also possible to specify a name starting
|
|
with the label *. Such a name is called a wildcard. The * in a wildcard
|
|
can match one or more labels in a queried name, but only whole labels.
|
|
Any other * characters in a wildcard, apart from the leading one,
|
|
will only match a literal *.
|
|
.br
|
|
For example, *.mydomain will match a.mydomain or www.a.mydomain, but not
|
|
mydomain. *.a*.mydomain will match www.a*.mydomain, but not www.ab.mydomain.
|
|
*a.mydomain will only match itself.
|
|
.br
|
|
Before you can specify an rr section with name=*.mydomain
|
|
you must define some records for mydomain, typically NS and/or SOA records.
|
|
Example:
|
|
.DS L
|
|
|
|
rr {
|
|
name = mydomain;
|
|
ns = localhost;
|
|
soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400;
|
|
}
|
|
rr {
|
|
name = *.mydomain;
|
|
a = 192.168.1.10;
|
|
}
|
|
.DE
|
|
|
|
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.
|
|
.TP
|
|
.B ttl=\fItimespec\fP;
|
|
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).
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
This is on by default.
|
|
.br
|
|
Please note that this only has an effect if it precedes the name option!
|
|
.TP
|
|
.B reverse=(on|off);
|
|
\fINew in version 1.2:\fP If you want a locally defined name to resolve to a numeric address
|
|
and vice versa, you can achieve this by setting reverse=on before defining the A record
|
|
(see below). The alternative is to define a separate PTR record, but you will
|
|
probably find this option much more convenient.
|
|
.br
|
|
The default is off.
|
|
.TP
|
|
.B a=\fIstring\fP;
|
|
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.
|
|
.br
|
|
Provided there is sufficient support in the C libraries and support for AAAA records was not
|
|
disabled, the argument string may also be an IPv6 address, in which case an AAAA record
|
|
will be defined.
|
|
.br
|
|
This option be may used multiple times within an 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.
|
|
.TP
|
|
.B ptr=\fIstring\fP;
|
|
Defines a PTR (domain name pointer) record. The argument is a host name in
|
|
dotted notation (see name). The ptr record is for resolving adresses into names. For example, if
|
|
you want the adress 127.0.0.1 to resolve into localhost, and localhost into 127.0.0.1, you need something
|
|
like the following sections:
|
|
.br
|
|
.DS L
|
|
|
|
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;
|
|
}
|
|
.DE
|
|
|
|
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.
|
|
.br
|
|
There is something special about the name in the second section:
|
|
when a resolver wants to get a host name from an internet address,
|
|
it composes an address that is built of the IP address in reverse byte order
|
|
(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.
|
|
.br
|
|
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.
|
|
.TP
|
|
.B cname=\fIstring\fP;
|
|
Defines a CNAME (canonical name) record.
|
|
The argument should be a fully-qualified host name in dotted notation (see name).
|
|
A CNAME is the DNS equivalent of an alias or symbolic link.
|
|
.br
|
|
A useful application for CNAMEs is giving short, easy to remember nicknames to hosts with complicated names.
|
|
For example, you might want the name "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".
|
|
.br
|
|
To implement this with pdnsd, you could add the following section to your configuration file:
|
|
.br
|
|
.DS L
|
|
|
|
rr {
|
|
name = news;
|
|
cname = nntp2.myisp.com;
|
|
owner = localhost;
|
|
}
|
|
.DE
|
|
|
|
.TP
|
|
.B mx=\fIstring\fP,\fInumber\fP;
|
|
Defines an MX (mail exchange) record. The string is the host name of the mail server in dotted notation (see name).
|
|
The number specifies the preference level.
|
|
.br
|
|
When you send mail to someone, your mail typically goes from your E-mail client to an SMTP server.
|
|
The SMTP server then checks for the MX record of the domain in the E-mail address.
|
|
For example, with 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.
|
|
.br
|
|
If there are multiple MX records, the SMTP server will pick one based on the preference level
|
|
(starting with the lowest preference number, working its way up).
|
|
.br
|
|
Don't define MX records with pdnsd unless you know what you're doing.
|
|
.TP
|
|
.B owner=\fIstring\fP;
|
|
or
|
|
.PD 0
|
|
.TP
|
|
.PD
|
|
.B ns=\fIstring\fP;
|
|
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.
|
|
.br
|
|
\fINote:\fP 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).
|
|
.TP
|
|
.B soa=\fIstring\fP,\fIstring\fP,\fInumber\fP,\fItimespec\fP,\fItimespec\fP,\fItimespec\fP,\fItimespec\fP;
|
|
This defines a soa (start of authority) record. The first string is the
|
|
domain name of the server and should be equal to the name you specified as
|
|
owner.
|
|
.br
|
|
The second string specifies the email address of the maintainer of the name
|
|
server. It is also specified as a domain name, so you will have to replace the
|
|
@ sign in the name with a dot (.) to get the name you have to specify here.
|
|
The next parameter (the first number) is the serial number of the record. You
|
|
should increment this number if you change the record.
|
|
.br
|
|
The 4th parameter is the refresh timeout. It specifies after what amount
|
|
of time a caching server should attempt to refresh the cached record.
|
|
.br
|
|
The 5th parameter specifies a time after which a caching server should attempt
|
|
to refresh the record after a refresh failure.
|
|
.br
|
|
The 6th parameter defines the timeout after which a cached record expires if it
|
|
has not been refreshed.
|
|
.br
|
|
The 7th parameter is the ttl that is specified in every rr and should be the
|
|
same as given with the ttl option (if you do not specify a ttl, use the default 86400).
|
|
.TP
|
|
.B txt=\fIstring\fP,...,\fIstring\fP;
|
|
\fINew in version 1.2.9:\fP
|
|
Defines an TXT record. You can specify one or more strings here.
|
|
|
|
.SS 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.
|
|
.br
|
|
This is useful if a certain application asks periodically for nonexisting hosts or
|
|
RR types and you do not want a query to go out every time the cached record has
|
|
timed out. Example: Netscape Communicator will ask for the servers news and mail
|
|
on startup if unconfigured. If you do not have a dns search list for your network,
|
|
you can inhibit outgoing queries for these by specifying
|
|
.br
|
|
.DS L
|
|
|
|
neg {
|
|
name = news;
|
|
types = domain;
|
|
}
|
|
neg {
|
|
name = mail;
|
|
types = domain;
|
|
}
|
|
.DE
|
|
|
|
in your config file. If you have a search list, you have to repeat that for any
|
|
entry in your search list in addition to the entries given above!
|
|
.br
|
|
In versions 1.1.11 and later, if you negate whole domains this way, all subdomains
|
|
will be negated as well. Thus if you specify
|
|
.br
|
|
neg {name=example.com; types=domain;} in the
|
|
config file, this will also negate www.example.com, xxx.adserver.example.com, etc.
|
|
|
|
.TP
|
|
.B name=\fIstring\fP;
|
|
Specifies the name of the domain for which negative cache entries are created.
|
|
This option must be specified before the types option.
|
|
Names are interpreted as absolute domain names (i.e. pdnsd
|
|
assumes they end in the root domain).
|
|
You need to specify domain names in dotted notation (example venera.isi.edu.).
|
|
.br
|
|
Previous versions of pdnsd
|
|
required that domain names given in the configuration file ended in a
|
|
dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
|
|
dot at the end if it is missing.
|
|
.TP
|
|
.B ttl=\fItimespec\fP;
|
|
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).
|
|
.TP
|
|
.B types=(domain|\fIrr_type\fP[,\fIrr_type\fP[,\fIrr_type\fP[,...]]]);
|
|
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.
|
|
.br
|
|
The RR types are specified using their official names from the RFC's in capitals,
|
|
e.g. A, CNAME, NS, PTR, MX,
|
|
AAAA, ...
|
|
.br
|
|
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.
|
|
|
|
.SS 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.
|
|
.br
|
|
The accepted format is as follows: The #\-sign initiates a comment, the rest of
|
|
the line from the first occurence of this character on is ignored. Empty lines
|
|
are tolerated.
|
|
.br
|
|
The first entry on a line (predeceded by an arbitrary number of tabs and spaces)
|
|
is the IP in dotted notation, the second entry on one line (separated by the
|
|
first by an arbitrary number of tabs and spaces) is the FQDN (fully qualified
|
|
domain name) for that ip. The rest of the line is ignored by default (in the original
|
|
/etc/hosts, it may contain information not needed by pdnsd).
|
|
|
|
.TP
|
|
.B owner=\fIstring\fP;
|
|
Specifies the name of the host pdnsd runs on and that are specified in dns
|
|
answers (specifically, nameserver records).
|
|
Must be specified before any file entries.
|
|
.br
|
|
Names are interpreted as absolute domain names (i.e. pdnsd
|
|
assumes they end in the root domain).
|
|
You need to specify domain names in dotted notation (example venera.isi.edu.).
|
|
.br
|
|
Previous versions of pdnsd
|
|
required that domain names given in the configuration file ended in a
|
|
dot, but since version 1.1.8b1-par8, pdnsd automatically assumes a
|
|
dot at the end if it is missing.
|
|
.TP
|
|
.B ttl=\fItimespec\fP;
|
|
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).
|
|
.TP
|
|
.B file=\fIstring\fP;
|
|
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.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
This feature was suggested by Bert Frederiks.
|
|
.br
|
|
It is off by default.
|
|
.TP
|
|
.B 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.
|
|
.br
|
|
This is on by default.
|
|
|
|
.SS 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.
|
|
.br
|
|
Include sections currently only have one type of option, which may be given multiple times within a single section.
|
|
|
|
.TP
|
|
.B file=\fIstring\fP;
|
|
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.
|
|
|
|
.SH "VERSION"
|
|
.PP
|
|
This man page is correct for version @fullversion@ of pdnsd.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
.BR pdnsd (8),
|
|
.BR pdnsd\-ctl (8)
|
|
.PP
|
|
More documentation is available in the \fBdoc/\fP subdirectory of the source,
|
|
or in \fB/usr/share/doc/pdnsd/\fP if you are using a binary package.
|
|
|
|
.SH AUTHORS
|
|
|
|
\fBpdnsd\fP was originally written by Thomas Moestl
|
|
.UR
|
|
<tmoestl@gmx.net>
|
|
.UE
|
|
and was extensively revised by Paul A. Rombouts
|
|
.UR
|
|
<p.a.rombouts@home.nl>
|
|
.UE
|
|
(for versions 1.1.8b1\-par and later).
|
|
.PP
|
|
Several others have contributed to \fBpdnsd\fP; see files in the source or
|
|
\fB/usr/share/doc/pdnsd/\fP directory.
|
|
.PP
|
|
This man page was automatically generated from the html documentation for \fBpdnsd\fP,
|
|
using a customized Perl script written by Paul A. Rombouts.
|
|
.PP
|
|
Last revised: 19 April 2012 by Paul A. Rombouts
|