The remote name daemon control
(rndc) program allows the
system
administrator to control the operation of a name server.
If rndc is run without any
options,
it displays a usage message as follows:
rndc [-c config] [-s server] [-p port] [-y key] command [command...]
See rndc(8) for details of
the available rndc commands.
rndc requires a configuration file,
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 also looks 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 is
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
is 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 accepts any string as the
argument
to algorithm, currently only the strings
"hmac-md5",
"hmac-sha1",
"hmac-sha224",
"hmac-sha256",
"hmac-sha384",
and "hmac-sha512"
have any meaning. The secret is a Base64-encoded string
as specified in RFC 3548.
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-sha256";
secret
"c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
};
options {
default-server 127.0.0.1;
default-key rndc_key;
};
This file, if installed as /etc/rndc.conf,
allows the command:
$ rndc reload
to connect to 127.0.0.1 port 953 and causes the name server
to reload, if a name server on the local machine is
running with
following controls statements:
controls {
inet 127.0.0.1
allow { localhost; } keys { rndc_key; };
};
and it has an identical key statement for
rndc_key.
Running the rndc-confgen
program
conveniently creates an rndc.conf
file, and also displays the
corresponding controls
statement needed to
add to named.conf.
Alternatively,
it is possible to run rndc-confgen -a
to set up
an rndc.key file and not
modify
named.conf at all.