pdnsd/doc/pdnsd.8.in

.TH PDNSD 8 "Jul 2007" "pdnsd @fullversion@" "System Administration Commands"

.SH NAME
\fBpdnsd\fP \- dns proxy daemon

.SH SYNOPSIS

\fBpdnsd\fP [\-h] [\-V] [\-s] [\-d] [\-g] [\-t] [\-p \fIfile\fR] [\-v\fIn\fR] [\-m\fIxx\fR] [\-c \fIfile\fR] [\-4] [\-6] [\-a]
.PP
This man page is an extract of the documentation of \fBpdnsd\fP.
For complete, current documentation, refer to the HTML (or plain text)
documentation (which you can find in the \fBdoc/\fP subdirectory of the
source or in a standard documentation directory, typically
\fB/usr/share/doc/pdnsd/\fP if you are using a binary package).

.SH DESCRIPTION
.PP
\fBpdnsd\fP is a IPv6 capable proxy domain name server (DNS) which
saves the contents of its DNS cache to the disk on exit.

.SH OPTIONS

.RS
.TP
.B \-4
enables IPv4 support. IPv6 support is automatically
disabled (should it be available). On by default.
.TP
.B \-6
enables IPv6 support. IPv4 support is automatically
disabled (should it be available). Off by default.
.TP
.B \-a
With this option, pdnsd will try to detect automatically if
the system supports IPv6, and fall back to IPv4 otherwise.
.TP
.BR \-V "  or  " \-\-version
Print version information and exit.
.TP
\fB\-c\fP \fIFILE\fP  or  \fB\-\-config\-file=\fP\fIFILE\fP
specifies that configuration is to be read from \fIFILE\fP.
Default is \fB@sysconfdir@/pdnsd.conf\fP.
.TP
.BR \-d "  or  " \-\-daemon
Start \fBpdnsd\fP in daemon mode (as a background process).
.TP
.BR \-g "  or  " \-\-debug
Print some debug messages on the console or to the file
\fBpdnsd.debug\fP in your cache directory (in daemon mode).
.TP
.BR \-h "  or  " \-\-help
Print an option summary and exit.
.TP
\fB\-i\fP \fIPREFIX\fP  or  \fB\-\-ipv4_6_prefix=\fP\fIPREFIX\fP
specifies the prefix pdnsd uses (when running in IPv6 mode) to map IPv4
addresses in the configuration file to IPv6 addresses. Must be a valid IPv6
address. Default is ::ffff:0.0.0.0
.TP
.B \-p \fIFILE\fP
writes the pid the server runs as to the specified filename. Works
only in daemon mode.
.TP
.B \-\-pdnsd\-user
Print the user \fBpdnsd\fP will run as and exit.
.TP
.BR \-s "  or  " \-\-status
enables the status control socket. Either this option should be passed
to the command line or \fBstatus_ctl=on;\fP should be specified in the
config file if you want to use
.BR pdnsd\-ctl (8)
to control \fBpdnsd\fP at runtime.
.TP
.BR \-t "  or  " \-\-tcp
enables the TCP server thread. \fBpdnsd\fP will then serve TCP and UDP
queries.
.TP
.BI \-v n
sets the verbosity of \fBpdnsd\fP. \fIn\fP is a numeric argument
between  0 (normal operation) to 3 (many messages for debugging).
.TP
.BI \-m xx
sets the query method \fBpdnsd\fP
uses. Possible values for \fIxx\fP are:
.IP
.B uo
\- pdnsd will use UDP only. This is the fastest method, and should
be supported by all name servers on the Internet.

.IP
.B to
\- pdnsd will use TCP only. TCP queries usually take more 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.

.IP
.B tu
\- pdnsd will try to use TCP, and will fall back to UDP if its
connection is refused or times out.

.IP
.B ut
\- pdnsd will try to use UDP, and will repeat the query using TCP
if the UDP reply was truncated (i.e. the tc bit is set).
This is the behaviour recommended by the DNS standards.

.PP
Additionally, "no" can be prepended to the \-\-status, \-\-daemon, \-\-debug
and \-\-tcp options (e.g. \-\-notcp) to reverse their effect.
.RE

.SH USAGE
.PP
\fBpdnsd\fP is usually run from a startup script. For \fBpdnsd\fP to
work, You need to:-

.IP
1. Tell your system to use \fBpdnsd\fP as the primary DNS server by
modifying \fB/etc/resolv.conf\fP.

.IP
2. Tell \fBpdnsd\fP to use an authentic source for DNS records, by
including the IP addresses of one or more DNS servers, usually your
ISP's DNS servers, in \fB@sysconfdir@/pdnsd.conf\fP.
.PP
For this, put the following line in your \fB/etc/resolv.conf\fP
.PP
.RS
nameserver 127.0.0.X
.RE
.PP
where X can be any number. (I use 3). Comment out all other
entries. You should put the same value in the server_ip= line in
\fBglobal\fP section of \fB@sysconfdir@/pdnsd.conf\fP.
.br
If you want to use \fBpdnsd\fP as the DNS server for a small local network,
you should use the IP address or name of the interface connected to
this network instead of 127.0.0.X.
.RE

.PP
To tell \fBpdnsd\fP where to get DNS information from, add the
following lines in \fB@sysconfdir@/pdnsd.conf\fP:-

.PP
.RS
server {
.br
        label= "myisp";
        ip=123.456.789.001,123.456.789.002;
        proxy_only=on;
        timeout=10;
.br
}
.RE
.PP
Note the opening and closing braces. Add more such \fBserver\fP
sections for each set of DNS servers you want \fBpdnsd\fP to query.
Of course the configuration options shown here are just examples.
More examples can be found in \fB@sysconfdir@/pdnsd.conf.sample\fP
or the pdnsd.conf in the documentation directory.
See the
.BR pdnsd.conf (5)
man page for all the possible options and their exact meaning.
.PP
If you use a dial up connection, remember that ppp scripts usually
replace \fB/etc/resolv.conf\fP when connection with the ISP is
established.  You need to configure ppp (or whatever you use to
establish a connection) so that \fB/etc/resolv.conf\fP is not replaced
every time a connection is established. Read the documentation for the
scripts run when your network comes up.
.PP
If you use pppconfig, specify `none' in the  `nameservers' option  in
the `advanced' tab. If you use multiple ISPs, you should  do this for
each connection/account.
.PP
If you use multiple ISPs, you should tell \fBpdnsd\fP which DNS servers
have become available by calling \fBpdnsd\-ctl\fP, the \fBpdnsd\fP
control utility, in a script (e.g. \fB/etc/ppp/ip\-up\fP when you use pppd)
that is run when the connection is established.
If the addresses of the DNS servers are obtained through some type of
dynamic configuration protocol (e.g. pppd with the usepeerdns
option or a DHCP client), you can pass the DNS server addresses as an extra
argument to \fBpdnsd\-ctl\fP to configure \fBpdnsd\fP at run time.
See the
.BR pdnsd\-ctl (8)
man page for details.

.SH FILES

\fB@sysconfdir@/pdnsd.conf\fP is the pdnsd configuration file.
The file format and configuration options are described in the
.BR pdnsd.conf (5)
man page. You can find examples of almost all options in
\fB@sysconfdir@/pdnsd.conf.sample\fP.
.PP
\fB@cachedir@/pdnsd.cache\fP
.PP
\fB@cachedir@/pdnsd.status\fP is the status control socket, which must be
enabled before you can use \fBpdnsd\-ctl\fP.
.PP
\fB/etc/init.d/pdnsd\fP (the name and location of the start-up script
may be different depending on your distribution.)
.PP
\fB/etc/resolv.conf\fP
.PP
\fB/etc/defaults/pdnsd\fP contains additional parameters or options
which may be passed to pdnsd at boot time. This saves the hassle of
fiddling with initscripts (not available on all distributions).

.SH BUGS
.PP
The verbosity option
.BI -v n
presently does not seem to have much effect on the amount of debug output.
.br
Report any remaining bugs to the authors.

.SH CONFORMING TO
.PP
\fBpdnsd\fP should comply with RFCs 1034 and 1035. As of version
1.0.0, RFC compliance has been improved and pdnsd is now believed (or
hoped?)  to be fully RFC compatible. It completely follows RFC 2181
(except for one minor issue in the FreeBSD port, see the
documentation).
.PP
It does \fINOT\fP support the following features, of which most are
marked optional, experimental or obsolete in these RFCs:


.IP
\(bu Inverse queries
.IP
\(bu Status queries
.IP
\(bu Completion queries
.IP
\(bu Namespaces other than IN (Internet)
.IP
\(bu AXFR and IXFR queries (whole zone transfers); since pdnsd does not maintain zones, that should not violate the standard

.PP
The following record types, that are extensions to the original DNS
standard, are supported if given as options at compile time. (if you
do not need them, you do not need to compile support for them into
pdnsd and save cache and executable space):

.IP
\(bu RP (responsible person, RFC 1183)
.IP
\(bu AFSDB (AFS database location, RFC 1183)
.IP
\(bu X25 (X25 address, RFC 1183)
.IP
\(bu ISDN (ISDN number/address, RFC 1183)
.IP
\(bu RT (route through, RFC 1183)
.IP
\(bu NSAP (Network Service Access Protocol address , RFC 1348)
.IP
\(bu PX (X.400/RFC822 mapping information, RFC 1995)
.IP
\(bu GPOS (geographic position, deprecated)
.IP
\(bu AAAA (IPv6 address, RFC 1886)
.IP
\(bu LOC (location, RFC 1876)
.IP
\(bu EID (Nimrod EID)
.IP
\(bu NIMLOC (Nimrod locator)
.IP
\(bu SRV (service record, RFC 2782)
.IP
\(bu ATMA (ATM address)
.IP
\(bu NAPTR (URI mapping, RFC 2168)
.IP
\(bu KX (key exchange, RFC 2230)

.SH SEE ALSO
.PP
.BR pdnsd\-ctl (8),
.BR pdnsd.conf (5),
.BR pppconfig (8),
.BR resolv.conf (5)
.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 written by Mahesh T. Pai
.UR
<paivakil@yahoo.co.in>
.UE
using the documents in \fB/usr/share/docs/pdnsd/\fP directory for Debian,
but can be used on other distributions too.
.PP
Last revised: 22 Jul 2007 by Paul A. Rombouts.

.SH COPYRIGHT

.PP
This man page 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.

.PP
You can find a copy of the GNU GPL in the file \fBCOPYING\fP in the source
or the \fB/usr/share/common\-licenses/\fP directory if you are using a
Debian system.