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