rndc.conf(4)

NAME

rndc.conf — rndc configuration file

DESCRIPTION

rndc.conf is the configuration file for rndc, the BIND 9 name server control utility. This file has a structure and syntax similar to the named configuration file, named.conf.

The standard (default) rndc configuration file is located at /etc/rndc.conf. The standard (default) named configuration file is located at /etc/named.conf.

Syntax

The syntax of the rndc.conf file is much simpler than that of the named.conf configuration file. It includes three statements and optional comments. Statement blocks are enclosed in braces and terminated with a semicolon. Clauses in the statements are also semicolon-terminated.

options {
        default-server defserver ;
        default-key defkey ;
        };

server servername {
        key keyname ;
        };

key keyname {
        algorithm algoname ;
        secret "secretvalue" ; 
        };

A servername or keyname must be quoted using double quotes if it matches a keyword, such as having a key named "key" .

The options Statement

The options statement specifies the default server and key definition for the configuration.

The default-server clause specifies the default server on which rndc runs, if the server is not specified with the -s option in the rndc command. defserver is the name or IP address of a name server that is specified in a server statement.

The default-key clause specifies the default key that will authenticate the server's commands and responses if a key is not specified with the -y option in the rndc command. defkey is the name of a key that is specified in a key statement.

The server Statement

The server statement specifies the servername of a name server, as a host name or an IP address.

The key clause specifies a keyname that matches a keyname in a key statement.

Multiple server statements are permitted.

The key Statement

The key statement specifies the name, keyname, and definition of a key.

The algorithm clause identifies the encryption algorithm, algoname. Currently only HMAC-MD5 is supported.

The secret clause contains the random key, secretvalue, that will be used for authentication. It is base-64-encoded, using the algorithm specified in the algorithm clause. secretvalue is enclosed in double quotes.

The BIND 9 program dnssec-keygen can be used to generate the secretvalue.

Multiple key statements are permitted.

Comments

The following comment styles are supported:

C:: /* comment */
C++:: // to end of line
UNIX:: # to end of line

Name Server Configuration

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.

WARNINGS

Currently, there is no way to specify the port on which rndc must run.

EXAMPLES

Example 1

Here is a sample rndc.conf file:

options {
        default-server  localhost;
        default-key     samplekey;
        };

server localhost {
                 key samplekey;
                 };

key samplekey {
               algorithm hmac-md5;
secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; 
              };

In this example, rndc will, by default, use the server at localhost (127.0.0.1) and the key named samplekey. Commands directed 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.

Example 2

To generate a random secretvalue with the rndc-confgen command (see rndc-confgen(1)):

$ rndc-confgen 

A complete rndc.conf file, including the randomly generated key, is written to standard output. Commented-out key and controls statements for named.conf are also written.

Example 3

To generate the secretvalue with the dnssec-keygen command (see dnssec-keygen(1)):

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

The base-64 secretvalue will appear in two files, Krndc.+157.+keyid.key and Krndc.+157.+keyid.private. After you copy the secretvalue into key statements in the rndc.conf and named.conf files, you can delete the .key and .private files.

AUTHOR

rndc.conf was developed by the Internet Systems Consortium (ISC).