NAME
pdnsd-ctl - controls pdnsd
SYNOPSIS
pdnsd-ctl [-c cachedir] [-q] command [arguments]
DESCRIPTION
pdnsd-ctl controls pdnsd, 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 pdnsd-ctl.
-c cachedir
Set the cache directory to cachedir (must match pdnsd setting).
This is only necessary if the directory differs from the default
specified at compile time.
-q Be quiet unless output is specified by the command or something
goes wrong.
COMMANDS
help [no arguments]
Print a command summary.
version [no arguments]
Print version and license info.
status [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.
server (index|label) (up|down|retest) [dns1[,dns2[,...]]]
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.
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.
record name (delete|invalidate)
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.
source fn owner [ttl] [(on|off)] [noauth]
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. noauth is used to
make the domains non-authoritative (this is similar to setting
authrec=off in the config file, please consult the pdnsd.conf(5)
man page for what that means). fn is the name of the file,
which must be readable by pdnsd.
add a addr name [ttl] [noauth]
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]
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. noauth is used to make
the domains non-authoritative (this is similar to setting
authrec=off in the config file, please consult the pdnsd.conf(5)
man page for what that means). If you want no other record than
the newly added in the cache, do pdnsd-ctl record name delete
before adding records.
neg name [type] [ttl]
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.
config filename
Reload pdnsd’s configuration file.
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.
include filename
Parse an include file.
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.
eval string
Parse a string as if part of an include file.
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.
empty-cache [[+|-]name ...]
Delete all entries in the cache matching include/exclude rules.
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.
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.
dump [name]
Print information stored in the cache about name. If name
begins with a dot and is not the root domain, information about
the names in the cache ending in name (including name without
the leading dot) will be printed. If name is not specified,
information about all the names in the cache will be printed.
list-rrtypes [no arguments]
List available rr types for the neg command. Note that those are
only used for the neg command, not for add!
BUGS
If you pipe the output of dump 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.
Report any remaining bugs to the authors.
AUTHORS
Thomas Moestl <tmoestl@gmx.net>
Paul Rombouts <p.a.rombouts@home.nl> (for versions 1.1.8b1-par and
later)
Last revised: 04 Sep 2008 by Paul Rombouts.
SEE ALSO
pdnsd(8), pdnsd.conf(5)