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

key <string> {
        algorithm <string>;
        secret <string>;
}; // may occur multiple times

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

server <string> {
        key <string>;
        port <integer>;
        source-address ( <ipv4_address> | * );
        source-address-v6 ( <ipv6_address> | * );
        addresses { ( <quoted_string> [ port <integer> ] [ dscp <integer> ] | <ipv4_address> [ port <integer> ] [ dscp <integer> ] | <ipv6_address> [ port <integer> ] [ dscp <integer> ] ); ... };
}; // may occur multiple times

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

options {
        default-key <string>;
        default-port <integer>;
        default-server <string>;
        default-source-address ( <ipv4_address> | * );
        default-source-address-v6 ( <ipv6_address> | * );
};

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:

    /*
 * This is a multi-line
 * comment.
 */

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

    /* This is the start of a comment.
   This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
   This is no longer in any comment. */

  • 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:

    // This is a comment. It continues to end of line.
// This next line is a new comment, even though it is
// logically part of the previous comment.

  • 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:

    # This is a comment. It continues to end of line.
# This next line is a new comment, even though it is
# logically part of the previous comment.

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:

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 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)