5.2. rndc.conf - rndc program's configuration

5.2.1. Description

rndc.conf is the configuration file for rndc(1), the remote control program for named(8).

5.2.2. Configuration grammar

The configuration file consists of configuration statements and comments. Statements end with a semicolon. Statements and comments are the only elements that can appear without enclosing braces. Many statements contain a block of sub-statements, which are also terminated with a semicolon. Clauses in the statements are also semi-colon terminated. See the Comments syntax section for a description of comments, and the Examples section for examples.

rndc.conf has a similar structure and syntax to named.conf(5), although rndc.conf's grammar is much simpler than that of named.conf(5). rndc.conf supports the following statements:

key
Defines a symbolic name for a control channel key of the specified algorithm and secret.
server
Defines a symbolic name for a nameserver, and includes configuration on how to communicate with it.
options
Defines default configuration values for rndc.

5.2.2.1. key statement

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 --- hmac-sha256 (default) and hmac-sha512 are supported. This is followed by a secret clause which contains the Base64 encoding (RFC 4648) of the algorithm's authentication key. The Base64 string is enclosed in double quotes.

See the Examples section for a command to generate a sample rndc.conf file with a key statement.

5.2.2.2. server statement

After the server keyword, the server statement contains a string which is the hostname or address for a nameserver. 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 will be used instead of the server name. Each address can take an optional port. If an source-address or source-address-v6 of supplied then these will be used to specify the IPv4 and IPv6 source addresses respectively.

5.2.2.3. options statement

The options statement contains the following clauses:

  • The default-server clause is followed by the name or address of the named nameserver. This host will be used when no nameserver 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 nameserver's commands and responses.
  • The default-port clause is followed by the port number to connect to on the remote nameserver. 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 number will be connected to.
  • The default-source-address clause is used to set the source IPv4 address.
  • The default-source-address-v6 clause is used to set the source IPv6 address.

Note

The options statement may only occur once in the configuration file.

5.2.3. Comments syntax

The comment syntax allows for comments to appear anywhere that whitespace may appear in a config file. To appeal to all programmers, they can be written in the C, C++, or shell/Perl style:

  • C-style comments start with the two characters /* (slash, star) and end with */ (star, slash). Because they are completely delimited within these characters, they can be used to comment only a portion of a line or to span multiple lines. For example:

    C-style comments cannot be nested. For example, the following syntax is not valid because the entire comment ends with the first */:

  • C++-style comments start with the two characters // (slash, slash) and continue to the end of the physical line. They cannot be continued across multiple physical lines; to have one logical comment span multiple lines, each line must use the // pair. For example:

  • Shell-style or Perl-style comments start with the character # (number/hash sign) and continue to the end of the physical line. They cannot be continued across multiple physical lines; to have one logical comment span multiple lines, each line must use the # character. For example:

Note

You cannot use the ; (semi-colon) character to start a comment such as you would in a zone file. The semicolon indicates the end of a configuration statement.

5.2.4. Examples

A sample rndc.conf file follows:

In the above sample, rndc will by default use the server localhost 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-sha256 algorithm and its secret clause contains the Base64 encoding of the hmac-sha256 secret enclosed in double quotes.

If rndc is then run with -s testserver arguments, then rndc will connect to the nameserver on localhost port 5353 using the key testkey.

To generate a sample rndc.conf, run rndc-confgen without arguments:

$ rndc-confgen
# Start of rndc.conf
key "rndc-key" {
        algorithm hmac-sha256;
        secret "6ttb0LmEkplPXfQ6wvcnwWUYhBfGlPjTwFA9hOYr1uw=";
};

options {
        default-key "rndc-key";
        default-server 127.0.0.1;
        default-port 953;
};
# End of rndc.conf

# Use with the following in named.conf, adjusting the allow list as needed:
# key "rndc-key" {
#       algorithm hmac-sha256;
#       secret "6ttb0LmEkplPXfQ6wvcnwWUYhBfGlPjTwFA9hOYr1uw=";
# };
#
# controls {
#       inet 127.0.0.1 port 953
#               allow { 127.0.0.1; } keys { "rndc-key"; };
# };
# End of named.conf
$

The content for a complete rndc.conf file, including a key statement with a randomly generated secret, will be written to the standard output. Commented-out key and controls statements for named.conf(5) are also printed.

5.2.5. Nameserver configuration

named(8) must be configured to accept control-channel connections and to recognize the key specified in the rndc.conf file, using the controls statement in named.conf(5).

5.2.6. See also

named(8), named.conf(5), rndc(1), rndc-confgen(1)