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)