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