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