1RNDC.CONF(5)                        BIND 9                        RNDC.CONF(5)
2
3
4

NAME

6       rndc.conf - rndc configuration file
7

SYNOPSIS

9       rndc.conf
10

DESCRIPTION

12       rndc.conf  is  the  configuration file for rndc, the BIND 9 name server
13       control utility. This file  has  a  similar  structure  and  syntax  to
14       named.conf.  Statements  are  enclosed  in braces and terminated with a
15       semi-colon. Clauses in the statements are also  semi-colon  terminated.
16       The usual comment styles are supported:
17
18       C style: /* */
19
20       C++ style: // to end of line
21
22       Unix style: # to end of line
23
24       rndc.conf  is  much simpler than named.conf. The file uses three state‐
25       ments: an options statement, a server statement, and a key statement.
26
27       The options statement contains five clauses. The default-server  clause
28       is  followed by the name or address of a name server. This host is used
29       when no name server is given as an argument to rndc.   The  default-key
30       clause  is  followed by the name of a key, which is identified by a key
31       statement. If no keyid is provided on the rndc command line, and no key
32       clause  is  found  in  a matching server statement, this default key is
33       used to authenticate the  server's  commands  and  responses.  The  de‐
34       fault-port  clause  is followed by the port to connect to on the remote
35       name server. If no port option is provided on the  rndc  command  line,
36       and  no  port  clause is found in a matching server statement, this de‐
37       fault port is used  to  connect.  The  default-source-address  and  de‐
38       fault-source-address-v6  clauses  can  be used to set the IPv4 and IPv6
39       source addresses respectively.
40
41       After the server keyword, the server statement includes a string  which
42       is  the  hostname or address for a name server. The statement has three
43       possible clauses: key, port, and addresses. The key name must match the
44       name of a key statement in the file. The port number specifies the port
45       to connect to. If an addresses clause is supplied, these addresses  are
46       used  instead  of  the  server  name. Each address can take an optional
47       port. If an source-address or source-address-v6 is supplied, it is used
48       to specify the IPv4 and IPv6 source address, respectively.
49
50       The  key  statement  begins with an identifying string, the name of the
51       key. The statement has two clauses. algorithm identifies the  authenti‐
52       cation algorithm for rndc to use; currently only HMAC-MD5 (for compati‐
53       bility), HMAC-SHA1, HMAC-SHA224,  HMAC-SHA256  (default),  HMAC-SHA384,
54       and  HMAC-SHA512  are  supported.  This  is followed by a secret clause
55       which contains the base-64 encoding of the  algorithm's  authentication
56       key. The base-64 string is enclosed in double quotes.
57
58       There  are  two  common ways to generate the base-64 string for the se‐
59       cret.  The BIND 9 program rndc-confgen can be used to generate a random
60       key,  or  the mmencode program, also known as mimencode, can be used to
61       generate a base-64 string from known input. mmencode does not ship with
62       BIND  9  but  is available on many systems. See the Example section for
63       sample command lines for each.
64

EXAMPLE

66          options {
67            default-server  localhost;
68            default-key     samplekey;
69          };
70
71          server localhost {
72            key             samplekey;
73          };
74
75          server testserver {
76            key     testkey;
77            addresses   { localhost port 5353; };
78          };
79
80          key samplekey {
81            algorithm       hmac-sha256;
82            secret          "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
83          };
84
85          key testkey {
86            algorithm   hmac-sha256;
87            secret      "R3HI8P6BKw9ZwXwN3VZKuQ==";
88          };
89
90       In the above example, rndc by default  uses  the  server  at  localhost
91       (127.0.0.1)  and  the key called "samplekey". Commands to the localhost
92       server use the "samplekey" key, which  must  also  be  defined  in  the
93       server's  configuration  file  with  the  same name and secret. The key
94       statement indicates that "samplekey" uses the HMAC-SHA256 algorithm and
95       its  secret clause contains the base-64 encoding of the HMAC-SHA256 se‐
96       cret enclosed in double quotes.
97
98       If rndc -s testserver is used, then rndc connects to the server on  lo‐
99       calhost port 5353 using the key "testkey".
100
101       To generate a random secret with rndc-confgen:
102
103       rndc-confgen
104
105       A  complete  rndc.conf  file,  including the randomly generated key, is
106       written to the standard output. Commented-out key and  controls  state‐
107       ments for named.conf are also printed.
108
109       To generate a base-64 secret with mmencode:
110
111       echo "known plaintext for a secret" | mmencode
112

NAME SERVER CONFIGURATION

114       The  name  server  must be configured to accept rndc connections and to
115       recognize the key specified in the rndc.conf file, using  the  controls
116       statement  in named.conf. See the sections on the controls statement in
117       the BIND 9 Administrator Reference Manual for details.
118

SEE ALSO

120       rndc(8), rndc-confgen(8), mmencode(1), BIND 9  Administrator  Reference
121       Manual.
122

AUTHOR

124       Internet Systems Consortium
125
127       2021, Internet Systems Consortium
128
129
130
131
1329.16.23-RH                                                        RNDC.CONF(5)
Impressum