man.rndc.conf.html revision 162933bac8fec492e683b1c09224344e568191e5
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - Copyright (C) 2004-2013 Internet Systems Consortium, Inc. ("ISC")
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - Copyright (C) 2000-2003 Internet Software Consortium.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - Permission to use, copy, modify, and/or distribute this software for any
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - purpose with or without fee is hereby granted, provided that the above
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - copyright notice and this permission notice appear in all copies.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter - PERFORMANCE OF THIS SOFTWARE.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<!-- $Id$ -->
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<link rel="prev" href="man.rndc.html" title="rndc">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<a name="man.rndc.conf"></a><div class="titlepage"></div>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<p><code class="filename">rndc.conf</code> is the configuration file
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter utility. This file has a similar structure and syntax to
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="filename">named.conf</code>. Statements are enclosed
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter in braces and terminated with a semi-colon. Clauses in
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter the statements are also semi-colon terminated. The usual
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter comment styles are supported:
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter C style: /* */
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter C++ style: // to end of line
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter Unix style: # to end of line
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<p><code class="filename">rndc.conf</code> is much simpler than
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="filename">named.conf</code>. The file uses three
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter statements: an options statement, a server statement
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter and a key statement.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter The <code class="option">options</code> statement contains five clauses.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter The <code class="option">default-server</code> clause is followed by the
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter name or address of a name server. This host will be used when
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter no name server is given as an argument to
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter clause is followed by the name of a key which is identified by
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter a <code class="option">key</code> statement. If no
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="option">keyid</code> is provided on the rndc command line,
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter and no <code class="option">key</code> clause is found in a matching
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="option">server</code> statement, this default key will be
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter used to authenticate the server's commands and responses. The
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="option">default-port</code> clause is followed by the port
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter to connect to on the remote name server. If no
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="option">port</code> option is provided on the rndc command
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter line, and no <code class="option">port</code> clause is found in a
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter matching <code class="option">server</code> statement, this default port
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter will be used to connect.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter The <code class="option">default-source-address</code> and
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <code class="option">default-source-address-v6</code> clauses which
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter can be used to set the IPv4 and IPv6 source addresses
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter respectively.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter After the <code class="option">server</code> keyword, the server
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter statement includes a string which is the hostname or address
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter for a name server. The statement has three possible clauses:
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <code class="option">key</code>, <code class="option">port</code> and
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <code class="option">addresses</code>. The key name must match the
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter name of a key statement in the file. The port number
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter specifies the port to connect to. If an <code class="option">addresses</code>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter clause is supplied these addresses will be used instead of
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter the server name. Each address can take an optional port.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter of supplied then these will be used to specify the IPv4 and IPv6
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter source addresses respectively.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter The <code class="option">key</code> statement begins with an identifying
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter string, the name of the key. The statement has two clauses.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <code class="option">algorithm</code> identifies the authentication algorithm
1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4Stef Walter for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4Stef Walter (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter (default), HMAC-SHA384 and HMAC-SHA512 are
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter supported. This is followed by a secret clause which contains
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter the base-64 encoding of the algorithm's authentication key. The
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter base-64 string is enclosed in double quotes.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter There are two common ways to generate the base-64 string for the
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter be used to generate a random key, or the
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <span><strong class="command">mmencode</strong></span> program, also known as
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <span><strong class="command">mimencode</strong></span>, can be used to generate a
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter string from known input. <span><strong class="command">mmencode</strong></span> does
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter ship with BIND 9 but is available on many systems. See the
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter EXAMPLE section for sample command lines for each.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter default-server localhost;
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter default-key samplekey;
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter server localhost {
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter key samplekey;
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter server testserver {
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter key testkey;
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter addresses { localhost port 5353; };
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter key samplekey {
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter algorithm hmac-sha256;
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter key testkey {
1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4Stef Walter algorithm hmac-sha256;
1319e71fd1680ca4864afe0b1aca2b8c8e4a1ee4Stef Walter secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter In the above example, <span><strong class="command">rndc</strong></span> will by
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter the server at localhost (127.0.0.1) and the key called samplekey.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter Commands to the localhost server will use the samplekey key, which
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter must also be defined in the server's configuration file with the
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter same name and secret. The key statement indicates that samplekey
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter uses the HMAC-SHA256 algorithm and its secret clause contains the
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek connect to server on localhost port 5353 using the key testkey.
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek<p><strong class="userinput"><code>rndc-confgen</code></strong>
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek A complete <code class="filename">rndc.conf</code> file, including
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter randomly generated key, will be written to the standard
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter output. Commented-out <code class="option">key</code> and
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="option">controls</code> statements for
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter <code class="filename">named.conf</code> are also printed.
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter<a name="id2646722"></a><h2>NAME SERVER CONFIGURATION</h2>
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter The name server must be configured to accept rndc connections and
b699c4d7f85a5404be1d1ee9450331aea869b886Stef Walter to recognize the key specified in the <code class="filename">rndc.conf</code>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter file, using the controls statement in <code class="filename">named.conf</code>.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter See the sections on the <code class="option">controls</code> statement in the
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter BIND 9 Administrator Reference Manual for details.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<p><span class="corpauthor">Internet Systems Consortium</span>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
dff909d473f43a6bd0f0286fa2d279c0ebe945c6Stef Walter<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
90e04eae7e54ec892a6f239783df94dab5d1ed9aJakub Hrozek<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>