pdnsd Homepage | pdnsd FAQ | Documentation | GNU GPL (pdnsd's License) | Download Section |
rpm -i pdnsd-<version>.rpm
/etc/pdnsd.conf
)
according to your needs (see below).
In the SuSE RPMs, a start script is also installed; read the section 0.4, Start at Boot Time
about that.
rpmbuild --rebuild pdnsd-<version>.src.rpm
rpmbuild -tb pdnsd-<version>.tar.gz
--with isdn
|
Has the same effect as --enable-isdn (see below).
|
--without poll
|
Has the same effect as --disable-poll (see below).
|
--with nptl
|
Has the same effect as --with-thread-lib=nptl (see below).
|
--with underscores
|
Has the same effect as --enable-underscores (see below).
|
--with ipv6
|
Has the same effect as --enable-ipv6 (see below).
|
--with tcpqueries
|
Has the same effect as --enable-tcp-queries (see below).
|
--without debug
|
Has the same effect as --with-debug=0 (see below).
|
--define "distro <distro>"
|
Has the same effect as --with-distribution=<distro> (see below).
|
--define "run_as_user <user>"
|
Has the same effect as --with-default-id=<user> (see below).For RPMs the default <user> is "pdnsd" .
|
--define "run_as_uid <uid>"
|
If the user defined by the previous option does not exist when the RPM is installed, the pre-install script will try to create a new user with numerical id <uid> .
|
--define "cachedir <dir>"
|
Has the same effect as --with-cachedir=<dir> (see below).
|
CFLAGS
.
Using a bash shell, you can do that on the command line like this:
CFLAGS="-O1 -Wall" rpmbuild ...
tar -xzf pdnsd-<version>.tar.gz
tar -xjf pdnsd-<version>.tar.bz2
gzip -dc pdnsd-<version>.tar.gz | tar -xf -
bzip2 -dc pdnsd-<version>.tar.bz2 | tar -xf -
--prefix
, --sysconfdir
and
--with-distribution
.
If you specify your distribution using --with-distribution
, this has the
following effects:
Generic
, no rc script is installled, and a generic spec
file is generated../configure --help
will give you a list of all supported command line
options.-O2
flag, but it might be safer to use a lower level of
optimization or no optimization at all. In that case prefix the
configure
command with the desired compiler flags like this
(assuming you're using a bash shell):
CFLAGS="-O1 -Wall" ./configure ...
make
in the source directory. Should work by now.make install
or do the installation by hand (see 0.3.4).make install
will do the following ($prefix is the prefix directory; see above):$(prefix)/sbin/
$(prefix)/sbin/
/etc/pdnsd.conf
to fit your needs (see below).
If you use the run_as
option, please make sure that your cache directory is owned by
the user you specified with this option!
/usr/sbin
).
docs/pdnsd.conf
into the directory you want it to reside (/etc
by default,
and change it according to your needs (see below).
/var/cache/pdnsd
(you may change this
in your pdnsd.conf
); Permisions should be at max rwxr-xr-x
(if you want to
protect your cache and status socket, make it rwx------
).
rc
folder of the pdnsd distribution are start scripts
for pdnsd designed for different Linux distros. There are scripts
for SuSE and Redhat Linux now.make install
if you specified your distro.
rc/SuSE/pdnsd
is a start script for SuSE Linux. It was tested for 6.? but should run on some
versions below. You can do make install
as root in the rc/SuSE
directory to install it, or you can install manually:manual installation |
For manual installation, copy rc/SuSE/pdnsd into /sbin/init.d/ , go to
/sbin/init.d/rc2.d/ and create there the following two symlinks:S11pdnsd to ../pdnsd (do ln -s ../pdnsd S11pdnsd in that dir) K34pdnsd to ../pdnsd (do ln -s ../pdnsd K34pdnsd in that dir) The numbers dictate the order different services are started and might need to be modified. Then edit your /etc/rc.config file and
add the line START_PDNSD=yes to start pdnsd at boot time.
|
If you used the make install
command, START_PDNSD=yes
has been
appended to your /etc/rc.config
file, causing pdnsd to be started
at boot time. If you don't want that, change the yes
into no
.
/sbin/init.d/skeleton
by me, so the
most is copyrighted by SuSE. They put it under the GPL, however, so
the license stated in COPYING also applies to this script.
There is NO WARRANTY OF ANY KIND on these scripts.
This is no official SuSE script, and SuSE naturally does NO support
for it.
rc/Redhat/pdnsd
is a start script for Red Hat Linux. It was contibuted by Torben
Janssen. make install
as root in the
rc/Redhat
directory to install it, or you can install manually:manual installation |
For manual installation, copy rc/Redhat/pdnsd into /etc/rc.d/init.d/ Then go to /etc/rc.d/rc3.d and create there the following symlink:S78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd S78pdnsd in that dir)Then go to /etc/rc.d/rc0.d and create there the following symlink:K78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd K78pdnsd in that dir)Then go to /etc/rc.d/rc6.d and create there the following symlink: K78pdnsd -> ../init.d/pdnsd (do ln -f -s ../init.d/pdnsd K78pdnsd in that dir)
|
pdnsd --help (or -h) gives you an overview of the pdnsd command line options.
pdnsd --version (or -V for short) prints licence and version information.
To start pdnsd as background daemon, specifiy --daemon (or -d for short) on the command line. Diagnostic and error messages after the actual daemon start will be printed to the syslog instead of the console. --nodaemon will disable this.
When starting pdnsd as a daemon, the -p option may be helpful: It writes the pid
of the server process to the file of the name given as argument to this option.
Example: pdnsd -d -p /var/run/pdnsd.pid
If you want to specify a configuration file other that /etc/pdnsd.conf, specify -c or --config-file on the command line, followed by a filename.
If pdnsd was compiled with debugging options enabled, you may specify -g or
--debug on the command line. This will cause extra diagnostic messages to be
printed. When pdnsd runs in deamon mode, the messages will be written to the pdnsd.debug
file in your cache directory. --nodebug disables debugging.
pdnsd -vn sets the verbosity level of pdnsd. n may be a digit from 0 to 3,
where 0 means normal operation, while 3 will most verbose. Example is -v2
The option -s or --status enables the status control socket. This is a named socket in
the cache directory called pdnsd.status
. This socket allows run-time configuration of pdnsd
using the utility pdnsd-ctl
. See below for more details about pdnsd-ctl
.
--nostatus disables status control.
See also the configuration option status_ctl
in the global section.
The option -t or --notcp disables the seldom needed TCP server thread, which may save you some resources. --tcp will enable it.
Using the -m option, you can select the method pdnsd uses to query other name servers. Following
methods are supported:
-muo: pdnsd will use UDP only. This is the fastest method, and should be supported by all name servers
on the internt.
-mto: pdnsd will use TCP only. TCP queries usually take longer time than UDP queries, but are more secure
against certain attacks, where an attacker tries to guess your query id and to send forged answers. TCP queries
are not supported by some name servers.
-mtu: pdnsd will try to use TCP, and will fall back to UDP if its connection is refused.
/etc/pdnsd.conf
. This may be changed
with the -c command line option.
An example pdnsd.conf comes with the pdnsd distribution in the docs directory
and will be installed to /etc/
by make install
.
option_name=option_value;
,;{}
".
(Note that these special characters are illegal in domain names anyway.)(option1|option2|option3|...)
global
Section
perm_cache=(number|<off>); Switch the disk cache off or supply a maximum cache size in kB. If the disk cache is switched off, 4 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; 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. Addtionally, it is possibly to bind pdnsd to listen on 127.0.0.2 to allow pdnsd to be a forwarder for BIND. pdnsd will listen on all of your local interfaces by default. The ip is treated as string and therefore needs to have quotation marks around it. |
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=number; This options sets the maximum time a record is hold in cache in seconds. 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=number; This options sets the minimum time a record is hold in cache in seconds. 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=number; This option sets the time that negative 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 negative, and additionally when record types are cached negative for a domain for which no SOA record is known to pdnsd. If a SOA is present, the ttl of the SOA is taken. |
neg_rrs_pol=(<on>|<off>|<auth>); This sets the RR set policy for negative cacheing; this tells pdnsd under which circumstances it should cache a record type negative for a certain domain. off will
turn the negative cacheing of record types off, on will always add a negative
cache entry when a name server did not return a record type we asked it for, and auth
will only add such entries if the answer came from an authoritative name server for that
domain. The preset is auth . This is normally the right thing, as some cacheing servers
behave strange.
|
neg_domain_pol=(<on>|<off>|<auth>); This is analogue to neg_rrs_pol for whole domain negative cacheing. The preset
is on here, because I have not seen a cacheing server that will falsely claim that a
domain does not exist. If you experience problems with false negatives, try setting this
to auth .
|
run_as=string; This option allows you to let pdnsd change its user and group id after operations that needed privileges have been done. This helps minimize security risks and is therefore recommended. The supplied string gives a user name whose user id and primary group id are taken. A little more details: after reading the config file, becoming a daemon (if specified) and starting the server status thread, the main thread changes its gid and uid, as do all newly created threads thereafter. By taking another uid and gid, those threads run with the privileges of the specified user. Under Linux and FreeBSD, the server status thread runs with the original privileges only when the strict_setuid option is set to off (see below, on by default), because these may be needed
for exec uptests. The manager thread also retains its original privileges in this case.
You should take care that the user you specify has write permissions on your cache file and
status pipe (if you need a status pipe). You should look out for error messages like "permission denied"
and "operation not permitted" to discover permission problems. |
strict_setuid=(<on>|<off>); When used together with the run_as option, this option lets you specify that all threads of the
program will run with the privileges of the run_as user. This provides higher security than
the normal run_as
option, but is not always possible. See the run_as option for further discussion.This option is on by default. Note that this option has no effect on Non-Linux systems. |
paranoid=(<on>|<off>); Normally, pdnsd queries all servers in recursive mode (i.e. instructs servers to query other servers themselves if possible, and to give back answers for domains that may not be in its authority), and accepts additional records with information for servers that are not in the authority of the queried server. This opens the possibility of so-called cache poisoning: a malicious attacker might set up a dns server that, when queried, returns forged additional records. This way, he might replace trusted servers with his own ones by making your dns server return bad IP addresses. This option protects you from cache poisoning by rejecting additional records that do not describe domains in the queried servers authority space and not doing recursive queries any more. An exception to this rule are the servers you specify in your config file, which are trusted. The penalty is a possible performance decrease, in particular, more queries might be necessary for the same operation. You should also notice that there may be other similar security problems, which are essentially problems of the DNS, i.e. any "traditional" server has them (the DNS security extensions solve these problems, but are not widely supported). One of this vulnerabilities is that an attacker may bombard you with forged answers in hopes that one may match a query you have done. If you have done such a query, one in 65536 forged packets will be succesful (i.e. an average packet count of 32768 is needed for that attack). pdnsd can use TCP for queries, which has a slightly higher overhead, but is much less vulnerable to such attacks on sane operating systems. Also, pdnsd chooses random query ids, so that an attacker cannot take a shortcut. If the attacker is able to listen to your network traffic, this attack is relatively easy, though. This vulnerability is not pdnsd's fault, and is possible using any conventional name server (pdnsd is perhaps a little more secured against this type of attacks if you make it use TCP). The paranoid option is off by default. |
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 disable this option.
|
daemon=(<on>|<off>); This has the same effect as the -d command line option: the daemon mode enabled when
on is specified.
|
tcp_server=(<on>|<off>); This has the same effect as the -t command line option: the tcp serving ability is enabled when
on is specified.
|
pid_file=string; This has the same effect as the -p command line option: you can specify a file that pdnsd
will write its pid into when it starts in daemon mode.
|
verbosity=number; This has the same effect as the -v command line option: you can set the verbosity of pdnsd's
messages with it. The argument is a number between 0 (few messages) to 3 (most messages).
|
query_method=(<tcp_only>|<udp_only>|<tcp_udp>); This has the same effect as the -m command line option. Read the documentation for the
command line option on this. tcp_only corresponds to the to , udp_only to
the uo and tcp_udp to the tu argument of the command line option.
|
run_ipv4=(<on>|<off>); This has the same effect as the -4 command line option: if on is specified, IPv4 support
is enabled, and IPv6 support is disabled (if available). ff off is specified, IPv4 will be disabled
and IPv6 will be enabled. You can only use this option if you have compiled pdnsd with IPv4 as well as
with IPv6 support.
|
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 are 20 query threads will be active (plus 3 to 6 threads that will always be present depending on your configuration). |
procq_limit=number; When the query thread 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.The default for this option is 30. |
tcp_qtimeout=number; 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 sets the maximum number of queries that will be executed in parallel, i.e. how many servers are simultaneously queried. This may speed up the query process if there are very slow servers to be quered (the first answer we get will be taken), but it will also increase network and server load. 1 or 2 are good values for this option. The default is set using the --with-par-queries option to configure .
|
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; If given, defines the start of the port range used for queries of pdnsd. The value given must be >= 1024. The purpose of this option is to aid certain firewall configurations that are based on the source port. Please keep in mind that another application may bind a port in that range, so a stateful firewall using 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 higher value is highly recommended, because other applications may also allocate ports in that
range. If possible, this range should be kept out of the space that other applications usually
use.
|
query_port_end=number; Only used if query_port_start is given. Defines the last port of the range started by query_port_start used for querys by pdnsd. The default is 65535, which is also the maximum legal value for this option. For details see the description of query_port_start .
|
delegation_only=string; Added by Paul Rombouts: This option specifies a "delegation-only" zone. This means that if pdnsd receives a query for a name that is in a subdomain of a "delegation-only" zone but the remote name server returns an answer with an authority section lacking any NS RRs for subdomains of that zone, pdnsd will answer NXDOMAIN (unknown domain). This feature can be used for undoing the undesired effects of DNS "wildcards". Several "delegation-only" zones may be specified together. Example: delegation_only="com","net"; |
server
Section
label=string; Specify a label for the server section. This can be used to refer to this section when using pdnsd-ctl , the pdnsd control utility.You can give several server sections the same label, but if you want to change the addresses of a server section (see ip option below) during run-time with
pdnsd-ctl server label up dns1,dns2,... ,
the label must be unique.
|
ip=string; Give the IP (the IP, not the hostname) 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; pdnsd-ctl ,
the pdnsd control utility.
|
port=number; Give the port the remote name server listens on. Default is 53 (the official dns port) |
uptest=(<ping>|<none>|<if>); Determine the method to check whether the server is available. Currently defined methods are:
The default value is |
ping_timeout=number; Sets the timeout for the ping test in tenth of seconds. The default is 600. |
ping_ip=string; The ip for the ping test. The default is the ip of the name server. |
uptest_cmd=string,string; or uptest_cmd=string; Sets the command for the uptest=exec function to the first string. If the second string is given, it specifies a user with whose user id and primary group id the command is executed. This is especially useful if you are executing the server as root, but do not want the uptest to be performed with root 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=number; Sets the interval for the server-up-test in seconds. The default is 900; however, a test is forced when a query times out. The interval timeout is reset then. If you specify onquery instead of a timeout, the interface will be tested before every query. This is to prevent automatically dialling interfaces (diald/pppd or ippp) to dial on dns queries. It is intended to be used in connection with a 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 this option with ping, as it may cause delays if the server does not answer (btw, it doesn't make sense anyway). Note also that using that option 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 configuration. |
interface=string; The network interface (or network device, eg "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=number; Set the timeout for the dns query in seconds. The default is 120. You probably want to set this lower. |
purge_cache=(<on>|<off>); In every fetched dns record, there is a cache timeout given, which specifies how long the fetched data may be cached until it needs to be reloaded. If purge_cache is set to off , the cached records are not purged
(unless the cache size would be exceeded, in this case the oldest records are purged).
Instead, they are still served if they cannot succesfully be
updated (eg. because all servers are down).
|
caching=(<on>|<off>); Specifies if caching shall be performed for this server at all. Default is on. |
lean_query=(<on>|<off>); Specifies whether to use the "lean" query mode. In this mode, only the information actually queried from pdnsd is resolved and cached. This has the advantage that usually less cache space is used and the query is usually faster. In 90% of the cases, only address (A) records are needed anyway. If switched off, pdnsd will always cache all data about a host it can find and will specifically ask for all available records (well, at least it is a good approximation for what it really does ;-) This will of course increase the answer packet sizes. Negative cacheing is only effective with lean_query activated. Some buggy name servers may not deliver CNAME records when not asked for all records. I do not know if such servers are around, but if you have trouble resolving certain hostnames, 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. |
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 control a server only via
pdnsd-ctl.
|
proxy_only=(<on>|<off>); When this option is set to on, answers given by the servers are always accepted, and no other servers (as, for example, 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. |
policy=(<included>|<excluded>|<simple_only>|<fqdn_only>); pdnsd supports inclusion/exclusion lists for server sections: with include=
and exclude= (see below) you can specify domain names for which this server
will be used or will not be used. The first match counts (i.e., the first include or
exclude rule in a server section that matches a domain name is applied, and the
search for other rules is terminated). If no rule matched a given domain name,
the policy= option determines whether this server is used for the
lookup for that domain name; when included is given, the server will
be asked, and when excluded is given, it will not.
If simple_only is given the server will be used if the name to lookup
is a simple host name, on the other hand if fqdn_only is given the server
will be used only for fully qualified domain names
(i.e. the name has at least one dot in-between).If no server is available for a queried domain, pdnsd will return an error message to the client that usually will stop the clients 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 simple host names.The default for this option is included .
|
include=string; This options 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."; Note added by Paul Rombouts: 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 options 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
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, soa or ptr 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.). Note added by Paul Rombouts: 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. |
owner=string; Specifies the name of the host pdnsd runs on and that is specified in dns answers (specifically, nameserver records). Must be specified before any a , ptr and soa entries.
|
ttl=number; 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 (and no IPv6 address), you normally don't want other name servers to be queried for it. This is on by default. Please note that this only has an effect if it precedes the name and owner options! |
a=string; Defines an A (host address) record. The argument is an IP in dotted notation. pdnsd will serve this address for the hostname given in the name option. |
ptr=string; Defines a PTR (domain name pointer) record. The argument is a host name in dotted notation (see name). The ptr record is for resolving adresses into names. For example, if you want to have the adress 127.0.0.1 into localhost, and localhost into 127.0.0.1, you need something like the following sections: rr { owner = localhost; name = localhost; a = 127.0.0.1; soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400; } rr { owner = localhost; name = 1.0.0.127.in-addr.arpa; ptr = localhost; soa = localhost, root.localhost, 42, 86400, 900, 86400, 86400; }The second section is for reverse resolving and uses the ptr option. There is something special about the name in the second section: when a resolver wants to get a hostname from an internet address, it composes an adress that is built of the IP address in reverse byte order ( 1.0.0.127 instead of 127.0.0.1 ) where each byte of the adress written
as number constitutes a sub-domain under the domain in-addr.arpa. So, if you want to compose an adress for reverse resolving, take your ip in dotted notation (eg 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 newsserver "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 newsserver changed, you 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 { owner = localhost; name = news; cname = nntp2.myisp.com; } |
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. |
soa=string,string,number,number,number,number,number; This defines a soa (record source information) 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 (the 2nd number) 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) All time parameters must be specified in seconds. |
neg
Sectionneg { 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!
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.). Note added by Paul Rombouts: 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=number; 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 negative: 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/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
./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.). Note added by Paul Rombouts: 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=number; 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.
|
-s
option (or use the status_ctl
option in the config file). You also should make sure that you
have appropriate permissions on the control socket (use the ctl_perms
option to make this sure) and of your pdnsd
cache directory (pdnsd keeps it's socket there). Please make sure the pdnsd cache directory is not writeable for untrusted users!-c
. It is used to specify the cache directory (and takes this as argument).
The default for this settings is the pdnsd default cache directory (specified at compile time). The cache directory for pdnsd-ctl must
be the same pdnsd uses!Command | Options | Description | |||||
help | print a command summary. | ||||||
version | print version info | ||||||
status | Print a description of pdnsd's cache status and configuration. Also shows which remote name servers are assumed to be available. | ||||||
server | (index|label) | (up|down|retest) | [dns1[,dns2[,...]]] |
Set the status of the server with the given index or label (where the given label
matches the one given with the label option in the respective server section in the config file)
to up or down, or force a retest. The index is assigned in the order of definition in
pdnsd.conf starting with 0. Use the status command to view the indices and labels.
You can specify all instead of an index or label to perform the action for all
servers registered with pdnsd. Example:pdnsd-ctl server 0 retest An optional third argument consisting of a list of IP addresses (separated by commas or spaces) can be given. This list will replace the previous list of addresses of name servers used by pdnsd in the specified section of the config file. For example in the /etc/ppp/ip-up script called by pppd you could
place the following line:pdnsd-ctl server isplabel up $DNS1,$DNS2 If spaces are used to separate addresses the list will have to be quoted. Spurious commas and spaces are ignored. The last argument may also be an empty string, in which case the existing IP addresses are removed and the corresponding server section becomes inactive. |
|||
record | name | (delete|invalidate) |
Delete or invalidate the record of the given domain name if it is in the
cache. Invalidation means that the record is marked as timed out, and
such is reloaded if possible (if purge_cache is set to on, it will
be deleted in any case). For local records (i.e., records that were given in the config file using a rr section, records read from a hosts-style file
and records added using pdnsd-ctl), invalidation has no effect. Deletion
will work, though. Example:pdnsd-ctl record localhost. delete
|
||||
source | fn | owner | [ttl] | [(on|off)] | [noauth] |
Load a hosts-style file. Works like using the pdnsd source option.
owner and ttl are used as in the source section. ttl has a default
of 900 (it does not need to be specified). The next to last option corresponds
to the serve_aliases option, and is off by default (i.e. if it is not specified).
noauth is used to make the domains non-authoritative - please see
the description of the authrec config file options for a description of what
that means.
fn is the filename. The file must be readable by pdnsd! Example:pdnsd-ctl source /etc/hosts localhost. 900 off
|
|
add | a | addr | name | [ttl] | [noauth] |
Add a record of the given type to the pdnsd cache, replacing existing
records for the same name and type. The 2nd argument corresponds
to the argument of the option in the rr section that is named like
the first option: a is a record for hostname-to-address mapping,
aaaa is the same thing for IPv6 addresses, and ptr is for address-to-hostname
mapping. See the documentation for the rr section for more details.
The ttl is optional, the default is 900 seconds.
noauth is used to make the domains non-authoritative - please see
the description of the authrec config file options for a description of what
that means.
If you want no other record than the newly added in the cache, dopdnsd-ctl record name delete
before adding records. This is also better when overwriting local records. Example:pdnsd-ctl add a 127.0.0.1 localhost. 900
|
|
add | aaaa | addr | name | [ttl] | [noauth] | ||
add | ptr | host | name | [ttl] | [noauth] | ||
add | cname | host | name | [ttl] | [noauth] | ||
add | mx | host | name | pref | [ttl] | [noauth] | |
neg | name | [type] | [ttl] |
Add a negative cached record to pdnsd's cache, replacing existing
records for the same name and type. If no type is given, the whole
domain is cached negative. For negative cached records, errors are
immediately returned on a query, without querying other servers first.
The ttl is optional, the default is 900 seconds. You can get a list of all types you can pass to this command using pdnsd-ctl list-rrtypes . The type is treated case-sensitive!
Example:pdnsd-ctl neg foo.bar A 900 pdnsd-ctl neg foo.baz 900 |
|||
list-rrtypes | List available rr types for the neg command. Note that those are only used for the neg command, not for add! |
README.par
and the ChangeLog
in the source directory (or /usr/share/doc/pdnsd-<version>
if you have installed an RPM) for more details.
If you have questions about my modifications, you can find my email address at the end of README.par
.
Makefile.am, configure.in, acconfig.h | autoconf/automake/autoheader scripts. Makefile.am's are in most subdirectories. |
pdnsd.spec.in | A template from which configure generates a spec file for building rpm's for various distributions. |
version | Contains only the program version string. Needed for several templates. |
src/rc/* | rc scripts for various linux distributions. |
src/cacheing/* | The pdnsd cache subsystem(s) as defined in src/cacheing/cache.h. There is the "traditional" pdnsd system in the subdirectory native. This system keeps the cache in memory and uses hash tables for accesses. Sourav K. Mandal is working on a system using gdbm. |
src/pdnsd-ctl/* | Contains the code for pdnsd-ctl, a program that allows to control pdnsd at run time. |
src/conf-lex.l.in | The lex/flex source file for the config file lexer. This is a template because there might be inserted "%option yylineno" for proper flex support. |
src/conf-lex.l. | This is automatically generated by configure from conf.l.templ. It may be overwritten in any make, so never modify this, but conf.l.templ instead! |
src/conf-parse.y | The yacc/bison source of the config file parser. |
src/conff.c, src/conff.h | The configuration handler functions and their prototypes. The parser is called from here. |
src/consts.h | Some constants used by lexer, parser, config file handler functions and in the server status thread, among others. |
src/dns.c, src/dns.h | Define dns message structures, constants, and some common dns data handlers. dns.h contains gcc-specific code (in praticular, "__attribute__((packed))"). |
src/dns_answer.c, src/dns_answer.h | Define functions that answer incoming dns queries. |
src/dns_query.c, src/dns_query.h | Define functions to manage outgoing dns queries. |
src/error.c, src/error.h | Functions for error output to stderr or the syslog. |
src/helpers.c, src/helpers.h | Define miscellaneous helper functions. |
src/icmp.c, src/icmp.h | Define a function for performing a ping test. This contains OS-specific code. |
src/main.c | Contains main(), which holds the command line parser, performs initialisations and signal handling. |
src/netdev.c, src/netdev.h | Define functions for network device handling. OS-specific. |
src/servers.c, src/servers.h | Define functions for the server status thread that performs the periodical uptests. |
src/status.c, src/status.h | Define functions for the status control thread. This is pdnsd's interface to pdnsd-ctl. |
Last revised: 06 Feb 2004 by Paul Rombouts