rndc.conf - rndc configuration file
rndc.conf
rndc.conf is the configuration file for
rndc, the BIND 9 name
server control utility. This file has a similar structure and syntax to
named.conf. Statements are enclosed in braces and terminated with a
semi-colon. Clauses in the statements are also semi-colon terminated. The
usual comment styles are supported:
C style: /* */
C++ style: // to end of line
Unix style: # to end of line
rndc.conf is much simpler than
named.conf. The file uses three
statements: an options statement, a server statement, and a key statement.
The
options statement contains five clauses. The
default-server
clause is followed by the name or address of a name server. This host is used
when no name server is given as an argument to
rndc. The
default-key clause is followed by the name of a key, which is
identified by a
key statement. If no
keyid is provided on the
rndc command line, and no
key clause is found in a matching
server statement, this default key is used to authenticate the server's
commands and responses. The
default-port clause is followed by the port
to connect to on the remote name server. If no
port option is provided
on the rndc command line, and no
port clause is found in a matching
server statement, this default port is used to connect. The
default-source-address and
default-source-address-v6 clauses can
be used to set the IPv4 and IPv6 source addresses respectively.
After the
server keyword, the server statement includes a string which is
the hostname or address for a name server. The statement has three possible
clauses:
key,
port, and
addresses. The key name must
match the name of a key statement in the file. The port number specifies the
port to connect to. If an
addresses clause is supplied, these addresses
are used instead of the server name. Each address can take an optional port.
If an
source-address or
source-address-v6 is supplied, it is
used to specify the IPv4 and IPv6 source address, respectively.
The
key statement begins with an identifying string, the name of the key.
The statement has two clauses.
algorithm identifies the authentication
algorithm for
rndc to use; currently only HMAC-MD5 (for compatibility),
HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default), HMAC-SHA384, and HMAC-SHA512
are supported. This is followed by a secret clause which contains the base-64
encoding of the algorithm's authentication key. The base-64 string is enclosed
in double quotes.
There are two common ways to generate the base-64 string for the secret. The
BIND 9 program
rndc-confgen can be used to generate a random key, or
the
mmencode program, also known as
mimencode, can be used to
generate a base-64 string from known input.
mmencode does not ship with
BIND 9 but is available on many systems. See the Example section for sample
command lines for each.
options {
default-server localhost;
default-key samplekey;
};
server localhost {
key samplekey;
};
server testserver {
key testkey;
addresses { localhost port 5353; };
};
key samplekey {
algorithm hmac-sha256;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
};
key testkey {
algorithm hmac-sha256;
secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
};
In the above example,
rndc by default uses the server at localhost
(127.0.0.1) and the key called "samplekey". Commands to the
localhost server use the "samplekey" key, which must also be defined
in the server's configuration file with the same name and secret. The key
statement indicates that "samplekey" uses the HMAC-SHA256 algorithm
and its secret clause contains the base-64 encoding of the HMAC-SHA256 secret
enclosed in double quotes.
If
rndc -s testserver is used, then
rndc connects to the server on
localhost port 5353 using the key "testkey".
To generate a random secret with
rndc-confgen:
rndc-confgen
A complete
rndc.conf file, including the randomly generated key, is
written to the standard output. Commented-out
key and
controls
statements for
named.conf are also printed.
To generate a base-64 secret with
mmencode:
echo "known plaintext for a secret" | mmencode
The name server must be configured to accept rndc connections and to recognize
the key specified in the
rndc.conf file, using the controls statement
in
named.conf. See the sections on the
controls statement in the
BIND 9 Administrator Reference Manual for details.
rndc(8),
rndc-confgen(8),
mmencode(1), BIND 9 Administrator
Reference Manual.
Internet Systems Consortium
2024, Internet Systems Consortium