rndc.conf.html revision 33d0a7767d53cb366039fd0ac4f63cf8a9c351b0
2dc5db0eb0ba6672fb1c23875e2a964e59c24cd1Tinderbox User - Copyright (C) 2004, 2005, 2007, 2013-2016 Internet Systems Consortium, Inc. ("ISC")
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Permission to use, copy, modify, and/or distribute this software for any
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - purpose with or without fee is hereby granted, provided that the above
9c49c394b4218cc9c743a372a8fcfb787f5ea8caAndreas Gustafsson - copyright notice and this permission notice appear in all copies.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
83a28ca274521e15086fc39febde507bcc4e145eMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
a8f6b2aa46f882c7c680b7bdab1dfb78a76787eaMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<a name="man.rndc.conf"></a><div class="titlepage"></div>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
704e6c8876907aac0bf7380effca8bca400d4acdMark Andrews<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<p><code class="filename">rndc.conf</code> is the configuration file
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
26e2a07a0b6a3b1eccef82ba31270d0c54ad4f06Mark Andrews utility. This file has a similar structure and syntax to
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews <code class="filename">named.conf</code>. Statements are enclosed
030aac3dbc57f99bad1d251b0783890ff0369952Automatic Updater in braces and terminated with a semi-colon. Clauses in
d60212e03fbef1d3dd7f7eb05c0545cc373cb9fcAutomatic Updater the statements are also semi-colon terminated. The usual
1b892cf691dd0907e0e75774df102dd4d92dd877Automatic Updater comment styles are supported:
938440694b33cd752e9e4b71a526368b4811c177Tinderbox User C style: /* */
2dc5db0eb0ba6672fb1c23875e2a964e59c24cd1Tinderbox User C++ style: // to end of line
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Unix style: # to end of line
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<p><code class="filename">rndc.conf</code> is much simpler than
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="filename">named.conf</code>. The file uses three
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein statements: an options statement, a server statement
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt and a key statement.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The <code class="option">options</code> statement contains five clauses.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt The <code class="option">default-server</code> clause is followed by the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt name or address of a name server. This host will be used when
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt no name server is given as an argument to
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt clause is followed by the name of a key which is identified by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt a <code class="option">key</code> statement. If no
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <code class="option">keyid</code> is provided on the rndc command line,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt and no <code class="option">key</code> clause is found in a matching
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="option">server</code> statement, this default key will be
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt used to authenticate the server's commands and responses. The
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="option">default-port</code> clause is followed by the port
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt to connect to on the remote name server. If no
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <code class="option">port</code> option is provided on the rndc command
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt line, and no <code class="option">port</code> clause is found in a
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt matching <code class="option">server</code> statement, this default port
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt will be used to connect.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">default-source-address</code> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <code class="option">default-source-address-v6</code> clauses which
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein can be used to set the IPv4 and IPv6 source addresses
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt respectively.
8f7de3db7ec299ddeded142905f5eb1f22076353Evan Hunt After the <code class="option">server</code> keyword, the server
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein statement includes a string which is the hostname or address
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for a name server. The statement has three possible clauses:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <code class="option">key</code>, <code class="option">port</code> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <code class="option">addresses</code>. The key name must match the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein name of a key statement in the file. The port number
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein specifies the port to connect to. If an <code class="option">addresses</code>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein clause is supplied these addresses will be used instead of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the server name. Each address can take an optional port.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of supplied then these will be used to specify the IPv4 and IPv6
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein source addresses respectively.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The <code class="option">key</code> statement begins with an identifying
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein string, the name of the key. The statement has two clauses.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <code class="option">algorithm</code> identifies the authentication algorithm
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (default), HMAC-SHA384 and HMAC-SHA512 are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein supported. This is followed by a secret clause which contains
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the base-64 encoding of the algorithm's authentication key. The
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein base-64 string is enclosed in double quotes.
8f7de3db7ec299ddeded142905f5eb1f22076353Evan Hunt There are two common ways to generate the base-64 string for the
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt be used to generate a random key, or the
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <span class="command"><strong>mmencode</strong></span> program, also known as
b98225ff8a5721a998ccb440df4d261488fef163Mark Andrews <span class="command"><strong>mimencode</strong></span>, can be used to generate a
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt string from known input. <span class="command"><strong>mmencode</strong></span> does
b98225ff8a5721a998ccb440df4d261488fef163Mark Andrews ship with BIND 9 but is available on many systems. See the
b98225ff8a5721a998ccb440df4d261488fef163Mark Andrews EXAMPLE section for sample command lines for each.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt default-server localhost;
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt default-key samplekey;
8f7de3db7ec299ddeded142905f5eb1f22076353Evan Hunt server localhost {
8f7de3db7ec299ddeded142905f5eb1f22076353Evan Hunt key samplekey;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt server testserver {
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews key testkey;
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt addresses { localhost port 5353; };
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt key samplekey {
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt algorithm hmac-sha256;
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt key testkey {
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt algorithm hmac-sha256;
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień In the above example, <span class="command"><strong>rndc</strong></span> will by
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień the server at localhost (127.0.0.1) and the key called samplekey.
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień Commands to the localhost server will use the samplekey key, which
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień must also be defined in the server's configuration file with the
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień same name and secret. The key statement indicates that samplekey
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień uses the HMAC-SHA256 algorithm and its secret clause contains the
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt connect to server on localhost port 5353 using the key testkey.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt<p><strong class="userinput"><code>rndc-confgen</code></strong>
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt A complete <code class="filename">rndc.conf</code> file, including
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt randomly generated key, will be written to the standard
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt output. Commented-out <code class="option">key</code> and
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <code class="option">controls</code> statements for
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <code class="filename">named.conf</code> are also printed.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt<a name="id-1.9"></a><h2>NAME SERVER CONFIGURATION</h2>
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt The name server must be configured to accept rndc connections and
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt to recognize the key specified in the <code class="filename">rndc.conf</code>
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt file, using the controls statement in <code class="filename">named.conf</code>.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt See the sections on the <code class="option">controls</code> statement in the
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt BIND 9 Administrator Reference Manual for details.
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
ca6e60cb704c4c8eea1385a9fbef3eaa476eca28Evan Hunt <em class="citetitle">BIND 9 Administrator Reference Manual</em>.