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