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