1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
2..
3.. SPDX-License-Identifier: MPL-2.0
4..
5.. This Source Code Form is subject to the terms of the Mozilla Public
6.. License, v. 2.0.  If a copy of the MPL was not distributed with this
7.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
8..
9.. See the COPYRIGHT file distributed with this work for additional
10.. information regarding copyright ownership.
11
12.. highlight: console
13
14.. _man_rndc.conf:
15
16rndc.conf - rndc configuration file
17-----------------------------------
18
19Synopsis
20~~~~~~~~
21
22:program:`rndc.conf`
23
24Description
25~~~~~~~~~~~
26
27``rndc.conf`` is the configuration file for ``rndc``, the BIND 9 name
28server control utility. This file has a similar structure and syntax to
29``named.conf``. Statements are enclosed in braces and terminated with a
30semi-colon. Clauses in the statements are also semi-colon terminated.
31The usual comment styles are supported:
32
33C style: /\* \*/
34
35C++ style: // to end of line
36
37Unix style: # to end of line
38
39``rndc.conf`` is much simpler than ``named.conf``. The file uses three
40statements: an options statement, a server statement, and a key
41statement.
42
43The ``options`` statement contains five clauses. The ``default-server``
44clause is followed by the name or address of a name server. This host
45is used when no name server is given as an argument to ``rndc``.
46The ``default-key`` clause is followed by the name of a key, which is
47identified by a ``key`` statement. If no ``keyid`` is provided on the
48rndc command line, and no ``key`` clause is found in a matching
49``server`` statement, this default key is used to authenticate the
50server's commands and responses. The ``default-port`` clause is followed
51by the port to connect to on the remote name server. If no ``port``
52option is provided on the rndc command line, and no ``port`` clause is
53found in a matching ``server`` statement, this default port is used
54to connect. The ``default-source-address`` and
55``default-source-address-v6`` clauses can be used to set the IPv4
56and IPv6 source addresses respectively.
57
58After the ``server`` keyword, the server statement includes a string
59which is the hostname or address for a name server. The statement has
60three possible clauses: ``key``, ``port``, and ``addresses``. The key
61name must match the name of a key statement in the file. The port number
62specifies the port to connect to. If an ``addresses`` clause is supplied,
63these addresses are used instead of the server name. Each address
64can take an optional port. If an ``source-address`` or
65``source-address-v6`` is supplied, it is used to specify the
66IPv4 and IPv6 source address, respectively.
67
68The ``key`` statement begins with an identifying string, the name of the
69key. The statement has two clauses. ``algorithm`` identifies the
70authentication algorithm for ``rndc`` to use; currently only HMAC-MD5
71(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default),
72HMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret
73clause which contains the base-64 encoding of the algorithm's
74authentication key. The base-64 string is enclosed in double quotes.
75
76There are two common ways to generate the base-64 string for the secret.
77The BIND 9 program ``rndc-confgen`` can be used to generate a random
78key, or the ``mmencode`` program, also known as ``mimencode``, can be
79used to generate a base-64 string from known input. ``mmencode`` does
80not ship with BIND 9 but is available on many systems. See the Example
81section for sample command lines for each.
82
83Example
84~~~~~~~
85
86::
87
88         options {
89           default-server  localhost;
90           default-key     samplekey;
91         };
92
93::
94
95         server localhost {
96           key             samplekey;
97         };
98
99::
100
101         server testserver {
102           key     testkey;
103           addresses   { localhost port 5353; };
104         };
105
106::
107
108         key samplekey {
109           algorithm       hmac-sha256;
110           secret          "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
111         };
112
113::
114
115         key testkey {
116           algorithm   hmac-sha256;
117           secret      "R3HI8P6BKw9ZwXwN3VZKuQ==";
118         };
119
120
121In the above example, ``rndc`` by default uses the server at
122localhost (127.0.0.1) and the key called "samplekey". Commands to the
123localhost server use the "samplekey" key, which must also be defined
124in the server's configuration file with the same name and secret. The
125key statement indicates that "samplekey" uses the HMAC-SHA256 algorithm
126and its secret clause contains the base-64 encoding of the HMAC-SHA256
127secret enclosed in double quotes.
128
129If ``rndc -s testserver`` is used, then ``rndc`` connects to the server
130on localhost port 5353 using the key "testkey".
131
132To generate a random secret with ``rndc-confgen``:
133
134``rndc-confgen``
135
136A complete ``rndc.conf`` file, including the randomly generated key,
137is written to the standard output. Commented-out ``key`` and
138``controls`` statements for ``named.conf`` are also printed.
139
140To generate a base-64 secret with ``mmencode``:
141
142``echo "known plaintext for a secret" | mmencode``
143
144Name Server Configuration
145~~~~~~~~~~~~~~~~~~~~~~~~~
146
147The name server must be configured to accept rndc connections and to
148recognize the key specified in the ``rndc.conf`` file, using the
149controls statement in ``named.conf``. See the sections on the
150``controls`` statement in the BIND 9 Administrator Reference Manual for
151details.
152
153See Also
154~~~~~~~~
155
156:manpage:`rndc(8)`, :manpage:`rndc-confgen(8)`, :manpage:`mmencode(1)`, BIND 9 Administrator Reference Manual.
157