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