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 three 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 + keyid is provided on the rndc command line, + and no key clause is found in a matching + server statement, this default key will be + 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 + will be used to connect. +
After the server keyword, the server statement + includes a string which is the hostname or address for a name + server. The statement has two possible clauses: + key and port. The key name must + match the name of a key statement in the file. The port number + specifies the port to connect to. +
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 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;
+ };
+
+ 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, 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-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 random 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. +