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