d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2013-2016 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews<a name="man.rndc.conf"></a><div class="titlepage"></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User — rndc configuration file
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><code class="filename">rndc.conf</code> is the configuration file
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein utility. This file has a similar structure and syntax to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename">named.conf</code>. Statements are enclosed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein in braces and terminated with a semi-colon. Clauses in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the statements are also semi-colon terminated. The usual
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein comment styles are supported:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein C style: /* */
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein C++ style: // to end of line
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Unix style: # to end of line
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><code class="filename">rndc.conf</code> is much simpler than
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename">named.conf</code>. The file uses three
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein statements: an options statement, a server statement
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and a key statement.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <code class="option">options</code> statement contains five clauses.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <code class="option">default-server</code> clause is followed by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein name or address of a name server. This host will be used when
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein no name server is given as an argument to
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein clause is followed by the name of a key which is identified by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a <code class="option">key</code> statement. If no
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">keyid</code> is provided on the rndc command line,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and no <code class="option">key</code> clause is found in a matching
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">server</code> statement, this default key will be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein used to authenticate the server's commands and responses. The
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">default-port</code> clause is followed by the port
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to connect to on the remote name server. If no
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">port</code> option is provided on the rndc command
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein line, and no <code class="option">port</code> clause is found in a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein matching <code class="option">server</code> statement, this default port
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein will be used to connect.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <code class="option">default-source-address</code> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">default-source-address-v6</code> clauses which
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein can be used to set the IPv4 and IPv6 source addresses
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein respectively.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein After the <code class="option">server</code> keyword, the server
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein statement includes a string which is the hostname or address
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein for a name server. The statement has three possible clauses:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">key</code>, <code class="option">port</code> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">addresses</code>. The key name must match the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein name of a key statement in the file. The port number
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein specifies the port to connect to. If an <code class="option">addresses</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein clause is supplied these addresses will be used instead of
f6da30bb5447c23d880b09f601441e70c5313557Mark Andrews the server name. Each address can take an optional port.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of supplied then these will be used to specify the IPv4 and IPv6
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein source addresses respectively.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The <code class="option">key</code> statement begins with an identifying
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein string, the name of the key. The statement has two clauses.
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User <code class="option">algorithm</code> identifies the authentication algorithm
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User (default), HMAC-SHA384 and HMAC-SHA512 are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein supported. This is followed by a secret clause which contains
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User the base-64 encoding of the algorithm's authentication key. The
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein base-64 string is enclosed in double quotes.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein There are two common ways to generate the base-64 string for the
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein be used to generate a random key, or the
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <span class="command"><strong>mmencode</strong></span> program, also known as
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <span class="command"><strong>mimencode</strong></span>, can be used to generate a
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User string from known input. <span class="command"><strong>mmencode</strong></span> does
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein ship with BIND 9 but is available on many systems. See the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein EXAMPLE section for sample command lines for each.
94bd918b63001277f1b28ae4581645f8a835688fBob Halley default-server localhost;
94bd918b63001277f1b28ae4581645f8a835688fBob Halley default-key samplekey;
94bd918b63001277f1b28ae4581645f8a835688fBob Halley server localhost {
94bd918b63001277f1b28ae4581645f8a835688fBob Halley key samplekey;
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews server testserver {
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews key testkey;
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews addresses { localhost port 5353; };
94bd918b63001277f1b28ae4581645f8a835688fBob Halley key samplekey {
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User algorithm hmac-sha256;
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews key testkey {
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User algorithm hmac-sha256;
36e0109263bd544578c245fe8db1e2718e8a8551Mark Andrews secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User In the above example, <span class="command"><strong>rndc</strong></span> will by
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the server at localhost (127.0.0.1) and the key called samplekey.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Commands to the localhost server will use the samplekey key, which
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein must also be defined in the server's configuration file with the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein same name and secret. The key statement indicates that samplekey
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User uses the HMAC-SHA256 algorithm and its secret clause contains the
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein connect to server on localhost port 5353 using the key testkey.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><strong class="userinput"><code>rndc-confgen</code></strong>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein A complete <code class="filename">rndc.conf</code> file, including
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein randomly generated key, will be written to the standard
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews output. Commented-out <code class="option">key</code> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="option">controls</code> statements for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="filename">named.conf</code> are also printed.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1.9"></a><h2>NAME SERVER CONFIGURATION</h2>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The name server must be configured to accept rndc connections and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to recognize the key specified in the <code class="filename">rndc.conf</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein file, using the controls statement in <code class="filename">named.conf</code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein See the sections on the <code class="option">controls</code> statement in the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein BIND 9 Administrator Reference Manual for details.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">rndc-confgen</span>(8)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">mmencode</span>(1)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="citetitle">BIND 9 Administrator Reference Manual</em>.