Ubuntu Manpage: pdnsd-ctl - controls pdnsd

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