pdnsd/doc/pdnsd-ctl.8

.\" This manpage has been automatically generated by docbook2man-spec
.\" from a DocBook document.  docbook2man-spec can be found at:
.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.\" This manpage has been edited manually by Paul A. Rombouts.
.TH "PDNSD\-CTL" "8" "Sep 2008" "pdnsd 1.2.9b-par" ""
.SH NAME
\fBpdnsd\-ctl\fP \- controls pdnsd
.SH SYNOPSIS
.sp
\fBpdnsd\-ctl\fP [\fB\-c\fP \fIcachedir\fP] [\fB\-q\fP] \fIcommand\fP [\fIarguments\fP]
.SH "DESCRIPTION"
.PP
\fBpdnsd\-ctl\fP controls \fBpdnsd\fP, a proxy dns server with permanent caching.
Note that the status control socket must be enabled (by specifying an option on
the pdnsd command line or in the configuration file) before you can use
\fBpdnsd\-ctl\fP.
.PP
.TP
\fB\-c\fP \fIcachedir\fP
Set the cache directory to \fIcachedir\fP (must match pdnsd setting).
This is only necessary if the directory differs from the default specified
at compile time.
.TP
\fB\-q\fP
Be quiet unless output is specified by the command or something goes wrong.
.SH "COMMANDS"
.TP
\fBhelp\fP\ \ \ [no arguments]

Print a command summary.
.TP
\fBversion\fP\ [no arguments]

Print version and license info.
.TP
\fBstatus\fP\ [no arguments]

Print a description of pdnsd's cache status, thread status and configuration.
Also shows which remote name servers are assumed to be available.
.TP
\fBserver\fP\ (\fIindex\fP|\fIlabel\fP) (\fBup\fP|\fBdown\fP|\fBretest\fP) [\fIdns1\fP[,\fIdns2\fP[,...]]]

Set the status of the servers with the given index or label 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 indexes. You can specify all
instead of an index to perform the action for all servers registered with pdnsd.
.IP
An optional third argument can be given consisting of a list of IP addresses
separated by commas or white-space characters. This list will replace the
addresses of name servers used by pdnsd for the given server section. This
feature is useful for run-time configuration of pdnsd with dynamic DNS data in
scripts called by ppp or DHCP clients. The last argument may also be an empty
string, which causes existing IP addresses to be removed and the corresponding
server section to become inactive.
.TP
\fBrecord\fP\ \fIname\fP (\fBdelete\fP|\fBinvalidate\fP)

Delete or invalidate the records of the given domain name if it is in the cache.
Invalidation means that the records are marked as timed out, and will be
reloaded if possible. 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.
.TP
\fBsource\fP\ \fIfn\fP \fIowner\fP [\fIttl\fP] [(\fBon\fP|\fBoff\fP)] [\fBnoauth\fP]

Load a hosts-style file. Works like using the pdnsd source configuration section.
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 argument corresponds
to the serve_aliases option, and is off by default.
\fBnoauth\fP is used to make the domains non-authoritative
(this is similar to setting authrec=off in the config file,
please consult the
.BR pdnsd.conf (5)
man page for what that means).
fn is the name of the file, which must be readable by pdnsd.
.TP
\fBadd\fP\ \ \ \ \fBa\fP \fIaddr\fP \fIname\fP [\fIttl\fP] [\fBnoauth\fP]
.TP
\fBadd\fP\ \ \ \ \fBaaaa\fP \fIaddr\fP \fIname\fP [\fIttl\fP] [\fBnoauth\fP]
.TP
\fBadd\fP\ \ \ \ \fBptr\fP \fIhost\fP \fIname\fP [\fIttl\fP] [\fBnoauth\fP]
.TP
\fBadd\fP\ \ \ \ \fBcname\fP \fIhost\fP \fIname\fP [\fIttl\fP] [\fBnoauth\fP]
.TP
\fBadd\fP\ \ \ \ \fBmx\fP \fIhost\fP \fIname\fP \fIpref\fP [\fIttl\fP] [\fBnoauth\fP]

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 value of the option in the rr section that is named like
the first argument. The addr argument may be a list of IP addresses,
separated by commas or white space.
The ttl is optional, the default is 900 seconds.
\fBnoauth\fP is used to make the domains non-authoritative
(this is similar to setting authrec=off in the config file,
please consult the
.BR pdnsd.conf (5)
man page for what that means).
If you want no other record than the newly added in the cache, do
\fBpdnsd\-ctl\fP\ \fBrecord\fP\ \fIname\fP\ \fBdelete\fP
before adding records.
.TP
\fBneg\fP\ \ \ \ \fIname\fP [\fItype\fP] [\fIttl\fP]

Add a negatively 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 negatively. For negatively cached records, errors are
immediately returned on a query, without querying other servers first.
The ttl is optional, the default is 900 seconds.
.TP
\fBconfig\fP\ \fIfilename\fP

Reload pdnsd's configuration file.
.br
The config file must be owned by the uid that pdnsd had when it was started,
and be readable by pdnsd's run_as uid.
If no file name is specified, the config file used at start-up is reloaded.
Note that some configuration changes, like the port or IP address pdnsd listens on,
cannot be made this way and you will receive an error message.
In these cases, you will have to restart pdnsd instead.
.TP
\fBinclude\fP\ \fIfilename\fP

Parse an include file.
.br
The include file may contain the same
type of sections as a config file, expect for global and server
sections, which are not allowed. This command can be used to add data
to the cache without reconfiguring pdnsd.
.TP
\fBeval\fP\ \ \ \fIstring\fP

Parse a string as if part of an include file.
.br
The string should hold one or more complete configuration sections,
but no global and server sections, which are not allowed.
If multiple strings are given, they will be joined using newline chars
and parsed together.
.TP
\fBempty\-cache\fP\ [[+|-]\fIname\fP ...]

Delete all entries in the cache matching include/exclude rules.
.br
If no arguments are provided, the cache is completely emptied,
freeing all existing entries.
Note that this also removes local records, as defined by the config file.
To restore local records, run "pdnsd-ctl\ config" immediately afterwards.
.br
If one or more arguments are provided, these are interpreted as 
include/exclude names. If an argument starts with a '+' the name is to
be included. If an argument starts with a '-' it is to be excluded.
If an argument does not begin with '+' or '-', a '+' is assumed.
If the domain name of a cache entry ends in one of the names in the
list, the first match will determine what happens. If the matching name
is to be included, the cache entry is deleted, otherwise it remains.
If there are no matches, the default action is not to delete.
.TP
\fBdump\fP\ \ \ [\fIname\fP]

Print information stored in the cache about \fIname\fP.
If \fIname\fP begins with a dot and is not the root domain, information
about the names in the cache ending in \fIname\fP (including \fIname\fP without
the leading dot) will be printed.
If \fIname\fP is not specified, information about all the names in the cache
will be printed.
.TP
\fBlist\-rrtypes\fP [no arguments]

List available rr types for the neg command. Note that those are only
used for the neg command, not for add!
.SH "BUGS"
.PP
If you pipe the output of \fBdump\fP command through an application that
reads only part of the output and then blocks (such as more or less),
pdnsd threads trying to add new entries to the cache will be suspended
until the pipe is closed.
It is preferable to capture the output in a file in such a case.
.br
Report any remaining bugs to the authors.
.SH "AUTHORS"
.PP
Thomas Moestl
.UR
<tmoestl@gmx.net>
.UE
.br
Paul A. Rombouts
.UR
<p.a.rombouts@home.nl>
.UE
(for versions 1.1.8b1\-par and later)
.PP
Last revised: 04 Sep 2008 by Paul A. Rombouts.
.SH "SEE ALSO"
.PP
.BR pdnsd (8),
.BR pdnsd.conf (5)