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