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