man.rndc.conf.html revision 2a9a5e1871710510cdbba67c13ce21e75296b451
72141595cf9d7faefcf7cf4fbab044c61a902b0fTinderbox User - Copyright (C) 2004-2008 Internet Systems Consortium, Inc. ("ISC")
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews - Copyright (C) 2000-2003 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - 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.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - 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.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<!-- $Id: man.rndc.conf.html,v 1.79 2008/05/02 01:11:50 tbox 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.71.1">
29747dfe5e073a299b3681e01f5c55540f8bfed7Mark Andrews<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<link rel="prev" href="man.rndc.html" title="rndc">
899f7f9af527d3dfe8345dcc8210d7c23fc950afDavid 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">
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny Mayer<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<a name="man.rndc.conf"></a><div class="titlepage"></div>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<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
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein comment styles are supported:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein C style: /* */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence C++ style: // to end of line
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence Unix style: # to end of line
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt<p><code class="filename">rndc.conf</code> is much simpler than
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt <code class="filename">named.conf</code>. The file uses three
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews statements: an options statement, a server statement
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence and a key statement.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence The <code class="option">options</code> statement contains five clauses.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein The <code class="option">default-server</code> clause is followed by the
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein name or address of a name server. This host will be used when
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein no name server is given as an argument to
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <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
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence 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
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <code class="option">default-port</code> clause is followed by the port
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence to connect to on the remote name server. If no
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <code class="option">port</code> option is provided on the rndc command
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater line, and no <code class="option">port</code> clause is found in a
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein matching <code class="option">server</code> statement, this default port
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein will be used to connect.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence The <code class="option">default-source-address</code> and
d409ceeda41a256e8114423674d844d5f5035ee8Bob Halley <code class="option">default-source-address-v6</code> clauses which
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence can be used to set the IPv4 and IPv6 source addresses
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson After the <code class="option">server</code> keyword, the server
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence statement includes a string which is the hostname or address
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein for a name server. The statement has three possible clauses:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <code class="option">key</code>, <code class="option">port</code> and
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence <code class="option">addresses</code>. The key name must match the
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson 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
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson the server name. Each address can take an optional port.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein of supplied then these will be used to specify the IPv4 and IPv6
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence source addresses respectively.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein The <code class="option">key</code> statement begins with an identifying
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence string, the name of the key. The statement has two clauses.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <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
8862388bcb44f634cbfc3e69f11ff4cb76590a4bMark Andrews 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.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein There are two common ways to generate the base-64 string for the
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence be used to generate a random key, or the
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence <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
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence string from known input. <span><strong class="command">mmencode</strong></span> does
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein ship with BIND 9 but is available on many systems. See the
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence EXAMPLE section for sample command lines for each.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence default-server localhost;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence default-key samplekey;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence server localhost {
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence key samplekey;
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny Mayer server testserver {
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein key testkey;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence addresses { localhost port 5353; };
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence key samplekey {
5fe5a0c02634eaadfcbc3528bf2c184557110a3bAndreas Gustafsson algorithm hmac-md5;
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
e502b133d630bda0ee64c1e2ce6729d96750d8abMark Andrews key testkey {
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt algorithm hmac-md5;
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence In the above example, <span><strong class="command">rndc</strong></span> will by
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence the server at localhost (127.0.0.1) and the key called samplekey.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein 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
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence connect to server on localhost port 5353 using the key testkey.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<p><strong class="userinput"><code>rndc-confgen</code></strong>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein 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
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence <code class="option">controls</code> statements for
863ac191b448a13ae1a3a8ee3458344e11602737David 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>:
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<a name="id2610056"></a><h2>NAME SERVER CONFIGURATION</h2>
863ac191b448a13ae1a3a8ee3458344e11602737David 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
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein BIND 9 Administrator Reference Manual for details.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<p><span class="corpauthor">Internet Systems Consortium</span>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<table width="100%" summary="Navigation footer">
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrence<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrence<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>