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