198944Sobrien.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 298944Sobrien.. 398944Sobrien.. SPDX-License-Identifier: MPL-2.0 498944Sobrien.. 598944Sobrien.. This Source Code Form is subject to the terms of the Mozilla Public 698944Sobrien.. License, v. 2.0. If a copy of the MPL was not distributed with this 798944Sobrien.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 898944Sobrien.. 998944Sobrien.. See the COPYRIGHT file distributed with this work for additional 1098944Sobrien.. information regarding copyright ownership. 1198944Sobrien 1298944Sobrien.. highlight: console 1398944Sobrien 1498944Sobrien.. iscman:: rndc.conf 1598944Sobrien.. program:: rndc.conf 1698944Sobrien.. _man_rndc.conf: 1798944Sobrien 1898944Sobrienrndc.conf - rndc configuration file 1998944Sobrien----------------------------------- 2098944Sobrien 2198944SobrienSynopsis 2298944Sobrien~~~~~~~~ 2398944Sobrien 2498944Sobrien:program:`rndc.conf` 2598944Sobrien 2698944SobrienDescription 2798944Sobrien~~~~~~~~~~~ 2898944Sobrien 2998944Sobrien:program:`rndc.conf` is the configuration file for :iscman:`rndc`, the BIND 9 name 3098944Sobrienserver control utility. This file has a similar structure and syntax to 3198944Sobrien:iscman:`named.conf`. Statements are enclosed in braces and terminated with a 3298944Sobriensemi-colon. Clauses in the statements are also semi-colon terminated. 3398944SobrienThe usual comment styles are supported: 3498944Sobrien 3598944SobrienC style: /\* \*/ 3698944Sobrien 3798944SobrienC++ style: // to end of line 3898944Sobrien 3998944SobrienUnix style: # to end of line 4098944Sobrien 4198944Sobrien:program:`rndc.conf` is much simpler than :iscman:`named.conf`. The file uses three 4298944Sobrienstatements: an options statement, a server statement, and a key 4398944Sobrienstatement. 4498944Sobrien 4598944SobrienThe ``options`` statement contains five clauses. The ``default-server`` 4698944Sobrienclause is followed by the name or address of a name server. This host 4798944Sobrienis used when no name server is given as an argument to :iscman:`rndc`. 4898944SobrienThe ``default-key`` clause is followed by the name of a key, which is 4998944Sobrienidentified by a ``key`` statement. If no ``keyid`` is provided on the 5098944Sobrienrndc command line, and no ``key`` clause is found in a matching 5198944Sobrien``server`` statement, this default key is used to authenticate the 5298944Sobrienserver's commands and responses. The ``default-port`` clause is followed 5398944Sobrienby the port to connect to on the remote name server. If no ``port`` 5498944Sobrienoption is provided on the rndc command line, and no ``port`` clause is 5598944Sobrienfound in a matching ``server`` statement, this default port is used 5698944Sobriento connect. The ``default-source-address`` and 5798944Sobrien``default-source-address-v6`` clauses can be used to set the IPv4 5898944Sobrienand IPv6 source addresses respectively. 5998944Sobrien 6098944SobrienAfter the ``server`` keyword, the server statement includes a string 6198944Sobrienwhich is the hostname or address for a name server. The statement has 6298944Sobrienthree possible clauses: ``key``, ``port``, and ``addresses``. The key 6398944Sobrienname must match the name of a key statement in the file. The port number 6498944Sobrienspecifies the port to connect to. If an ``addresses`` clause is supplied, 6598944Sobrienthese addresses are used instead of the server name. Each address 6698944Sobriencan take an optional port. If an ``source-address`` or 6798944Sobrien``source-address-v6`` is supplied, it is used to specify the 6898944SobrienIPv4 and IPv6 source address, respectively. 6998944Sobrien 7098944SobrienThe ``key`` statement begins with an identifying string, the name of the 7198944Sobrienkey. The statement has two clauses. ``algorithm`` identifies the 7298944Sobrienauthentication algorithm for :iscman:`rndc` to use; currently only HMAC-MD5 7398944Sobrien(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (default), 7498944SobrienHMAC-SHA384, and HMAC-SHA512 are supported. This is followed by a secret 7598944Sobrienclause which contains the base-64 encoding of the algorithm's 7698944Sobrienauthentication key. The base-64 string is enclosed in double quotes. 7798944Sobrien 7898944SobrienThere are two common ways to generate the base-64 string for the secret. 7998944SobrienThe BIND 9 program :iscman:`rndc-confgen` can be used to generate a random 8098944Sobrienkey, or the ``mmencode`` program, also known as ``mimencode``, can be 8198944Sobrienused to generate a base-64 string from known input. ``mmencode`` does 8298944Sobriennot ship with BIND 9 but is available on many systems. See the Example 8398944Sobriensection for sample command lines for each. 8498944Sobrien 8598944SobrienExample 8698944Sobrien~~~~~~~ 8798944Sobrien 8898944Sobrien:: 8998944Sobrien 9098944Sobrien options { 9198944Sobrien default-server localhost; 9298944Sobrien default-key samplekey; 9398944Sobrien }; 9498944Sobrien 9598944Sobrien:: 9698944Sobrien 9798944Sobrien server localhost { 9898944Sobrien key samplekey; 9998944Sobrien }; 10098944Sobrien 10198944Sobrien:: 10298944Sobrien 10398944Sobrien server testserver { 10498944Sobrien key testkey; 10598944Sobrien addresses { localhost port 5353; }; 10698944Sobrien }; 10798944Sobrien 10898944Sobrien:: 10998944Sobrien 11098944Sobrien key samplekey { 11198944Sobrien algorithm hmac-sha256; 11298944Sobrien secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz"; 11398944Sobrien }; 11498944Sobrien 11598944Sobrien:: 11698944Sobrien 11798944Sobrien key testkey { 11898944Sobrien algorithm hmac-sha256; 11998944Sobrien secret "R3HI8P6BKw9ZwXwN3VZKuQ=="; 12098944Sobrien }; 12198944Sobrien 12298944Sobrien 12398944SobrienIn the above example, :iscman:`rndc` by default uses the server at 12498944Sobrienlocalhost (127.0.0.1) and the key called "samplekey". Commands to the 12598944Sobrienlocalhost 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