The remote name daemon control
(rndc) program allows the system
administrator to control the operation of a name server.
If you run rndc without any options
it will display a usage message as follows:
rndc
[-c config
] [-s server
] [-p port
] [-y key
] command
[command
...]
The command is one of the following:
reload
Reload configuration file and zones.
reload zone
[class
[view
]]
Reload the given zone.
refresh zone
[class
[view
]]
Schedule zone maintenance for the given zone.
retransfer zone
[class
[view
]]
Retransfer the given zone from the master.
freeze [zone
[class
[view
]]]
Suspend updates to a dynamic zone. If no zone is specified,
then all zones are suspended. This allows manual
edits to be made to a zone normally updated by dynamic update. It
also causes changes in the journal file to be synced into the master
and the journal file to be removed. All dynamic update attempts will
be refused while the zone is frozen.
thaw [zone
[class
[view
]]]
Enable updates to a frozen dynamic zone. If no zone is
specified, then all frozen zones are enabled. This causes
the server to reload the zone from disk, and re-enables dynamic updates
after the load has completed. After a zone is thawed, dynamic updates
will no longer be refused.
reconfig
Reload the configuration file and load new zones,
but do not reload existing zone files even if they have changed.
This is faster than a full reload when there
is a large number of zones because it avoids the need to examine the
modification times of the zones files.
stats
Write server statistics to the statistics file.
querylog
Toggle query logging. Query logging can also be enabled
by explicitly directing the queries
category to a channel in the
logging section of
named.conf
.
dumpdb [-all|-cache|-zone] [view ...
]
Dump the server's caches (default) and / or zones to the
dump file for the specified views. If no view is specified, all
views are dumped.
stop [-p]
Stop the server, making sure any recent changes
made through dynamic update or IXFR are first saved to the master files
of the updated zones. If -p is specified named's process id is returned.
This allows an external process to determine when named had completed stopping.
halt [-p]
Stop the server immediately. Recent changes
made through dynamic update or IXFR are not saved to the master files,
but will be rolled forward from the journal files when the server
is restarted. If -p is specified named's process id is returned.
This allows an external process to determine when named had completed
stopping.
trace
Increment the servers debugging level by one.
trace level
Sets the server's debugging level to an explicit
value.
notrace
Sets the server's debugging level to 0.
flush
Flushes the server's cache.
flushname
name
Flushes the given name from the server's cache.
status
Display status of the server.
Note that the number of zones includes the internal bind/CH zone
and the default ./IN hint zone if there is not an
explicit root zone configured.
recursing
Dump the list of queries named is currently recursing
on.
In BIND 9.2, rndc
supports all the commands of the BIND 8 ndc
utility except ndc start and
ndc restart, which were also
not supported in ndc's channel mode.
A configuration file is required, since all
communication with the server is authenticated with
digital signatures that rely on a shared secret, and
there is no way to provide that secret other than with a
configuration file. The default location for the
rndc configuration file is
/etc/rndc.conf
, but an alternate
location can be specified with the -c
option. If the configuration file is not found,
rndc will also look in
/etc/rndc.key
(or whatever
sysconfdir
was defined when
the BIND build was configured).
The rndc.key
file is generated by
running rndc-confgen -a as described in
the section called “controls Statement Definition and Usage”.
The format of the configuration file is similar to
that of named.conf
, but limited to
only four statements, the options,
key, server and
include
statements. These statements are what associate the
secret keys to the servers with which they are meant to
be shared. The order of statements is not
significant.
The options statement has three clauses:
default-server, default-key,
and default-port.
default-server takes a
host name or address argument and represents the server that will
be contacted if no -s
option is provided on the command line.
default-key takes
the name of a key as its argument, as defined by a key statement.
default-port specifies the port to which
rndc should connect if no
port is given on the command line or in a
server statement.
The key statement defines a key to be used
by rndc when authenticating with
named. Its syntax is identical to the
key statement in named.conf.
The keyword key
is
followed by a key name, which must be a valid
domain name, though it need not actually be hierarchical; thus,
a string like "rndc_key
" is a valid name.
The key statement has two clauses:
algorithm and secret.
While the configuration parser will accept any string as the argument
to algorithm, currently only the string "hmac-md5
"
has any meaning. The secret is a base-64 encoded string.
The server statement associates a key
defined using the key statement with a server.
The keyword server
is followed by a
host name or address. The server statement
has two clauses: key and port.
The key clause specifies the name of the key
to be used when communicating with this server, and the
port clause can be used to
specify the port rndc should connect
to on the server.
A sample minimal configuration file is as follows:
key rndc_key {
algorithm "hmac-md5";
secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
};
options {
default-server 127.0.0.1;
default-key rndc_key;
};
This file, if installed as /etc/rndc.conf
,
would allow the command:
$
rndc reload
to connect to 127.0.0.1 port 953 and cause the name server
to reload, if a name server on the local machine were running with
following controls statements:
controls {
inet 127.0.0.1 allow { localhost; } keys { rndc_key; };
};
and it had an identical key statement for
rndc_key
.
Running the rndc-confgen program will
conveniently create a rndc.conf
file for you, and also display the
corresponding controls statement that you need to
add to named.conf
. Alternatively,
you can run rndc-confgen -a to set up
a rndc.key
file and not modify
named.conf
at all.