RDNC.CONF(5)

NAME
rdnc.conf - rdnc configuration file

SYNOPSIS
rdnc.conf

DESCRIPTION
The BIND9 utility for controlling the name server, rndc, has its own configuration file /etc/rndc.conf. This file has a similar structure and syntax to named.conf, the file used to configure the name server. 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 two clauses. The default-server clause is followed by the name or address of a name server. This host will be 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 -y option is provided on the rndc command line, and no key clause is found in a a matching server{} statement, this default key will be used to authenticate the server's commands and responses.

After the keyword server, the server{} statement is followed by a string which is the hostname or address for a name server. The statement has a single clause, key. The key name must match the name of a key{} statement in the file.

The key{} statement begins with an identifying string, the name of the key. The statement has two clauses. algorithm identifies the encryption algorithm for rndc to use; currently only HMAC-MD5 is supported. This is followed by a secret clause which contains the base-64 encoding of the algorithm's encryption 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 dnssec-keygen(8) can be used to generate a random key, or the mmencode(1) program, also known as mimencode(1), 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 EXAMPLES section for sample command lines for each.

Host and key names must be quoted using double quotes if they match a keyword, such as having a key named "key".

EXAMPLE

    options {
        default-server  localhost;
        default-key     samplekey;
    };
    server localhost {
        key     samplekey;
    };
    key samplekey {
        algorithm hmac-md5;
        secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
    };

In the above example, rndc will by default use the server at localhost (127.0.0.1) and the key called samplekey. Commands to the localhost server will use the samplekey key. The key{} statement indicates that samplekey uses the HMAC-MD5 algorithm and its secret clause contains the base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.

To generate a random secret with dnssec-keygen:

    $ dnssec-keygen -a hmac-md5 -b 128 -n user rndc

The base-64 string will appear in two files, Krndc.+157.+{random}.key and Krndc.+157.+{random}.private. After extracting the key to be placed in the rndc.conf and named.conf key{} statements, the .key and .private files can be removed.

To generate a secret from known input with mmenode:

    $ echo "known plaintext for a secret" | mmencode

LIMITATIONS
There is currently no way to specify the port for rndc to use. This will be remedied in future releases by allowing a port clause to the server{} statement and a default-port clause to the options{} statement.

SEE ALSO
rndc(8), named.conf(8), dnssec-keygen(8), mmencode(1), "BIND9 Administrators Manual".