man.rndc.conf.html revision 4abdfc917e6635a7c81d1f931a0c79227e72d025
8cbf3b6fc35091abde426930f2eadb8f53476c98Evan Hunt - Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC")
8cbf3b6fc35091abde426930f2eadb8f53476c98Evan Hunt - Copyright (C) 2000-2003 Internet Software Consortium.
8cbf3b6fc35091abde426930f2eadb8f53476c98Evan Hunt - Permission to use, copy, modify, and distribute this software for any
7bd455641455950eff7d21be652c8142b134d32fTinderbox User - purpose with or without fee is hereby granted, provided that the above
7b46a4aa418de3e1f2df63b9353b7148584afe64Evan Hunt - copyright notice and this permission notice appear in all copies.
9ba2cef72dacb1dc1105415956e1c311ac25d02cEvan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9ba2cef72dacb1dc1105415956e1c311ac25d02cEvan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9ba2cef72dacb1dc1105415956e1c311ac25d02cEvan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
78f79084fcfc40f1237c99e2d4325b24b750d012Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
78f79084fcfc40f1237c99e2d4325b24b750d012Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
78f79084fcfc40f1237c99e2d4325b24b750d012Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a2fd1de97d9ff685697aadba7f67a450557b0a06Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
a2fd1de97d9ff685697aadba7f67a450557b0a06Evan Hunt<!-- $Id: man.rndc.conf.html,v 1.42 2007/01/26 23:29:04 marka Exp $ -->
cc2a5156841ec6dfe1e90eed40c65fa8cdec246dTinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d51456e4537729c2263303350abeff45379b1105Evan Hunt<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
d51456e4537729c2263303350abeff45379b1105Evan Hunt<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
d51456e4537729c2263303350abeff45379b1105Evan Hunt<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
d51456e4537729c2263303350abeff45379b1105Evan Hunt<link rel="prev" href="man.rndc.html" title="rndc">
e69790ac0067c0034f57e070d513833550786a93Evan Hunt<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
e69790ac0067c0034f57e070d513833550786a93Evan Hunt<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
67d01dcacb2051a03377c8ec5c0e36604c17aea5Evan Hunt<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
6be12fa63b38fe7648811e042c9aad58cee2ead7Evan Hunt<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
6be12fa63b38fe7648811e042c9aad58cee2ead7Evan Hunt<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
084ba95b083dc55fd10631ad43fa8fff48707648Evan Hunt<a name="man.rndc.conf"></a><div class="titlepage"></div>
3ef4b7383ab4310df48ee5143e361ab1cfa3c8e8Evan Hunt<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
368aedf188d7c7782cae8a5ce2a978be47b5a764Evan Hunt<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
e71905610c72f474a2943934a48f43121c79c939Evan Hunt<p><code class="filename">rndc.conf</code> is the configuration file
e71905610c72f474a2943934a48f43121c79c939Evan Hunt for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
1aced7b8702288f656ded594cd5bd7678bb4fe70Evan Hunt utility. This file has a similar structure and syntax to
1aced7b8702288f656ded594cd5bd7678bb4fe70Evan Hunt <code class="filename">named.conf</code>. Statements are enclosed
1aced7b8702288f656ded594cd5bd7678bb4fe70Evan Hunt in braces and terminated with a semi-colon. Clauses in
a60bf97f9f7dcde6f4ca6e8188245fb0866200dbEvan Hunt the statements are also semi-colon terminated. The usual
a60bf97f9f7dcde6f4ca6e8188245fb0866200dbEvan Hunt comment styles are supported:
a60bf97f9f7dcde6f4ca6e8188245fb0866200dbEvan Hunt C style: /* */
f79ee00c69259b9a27f9f0d12afa6c7b64005dedEvan Hunt C++ style: // to end of line
7fbbc9bfd34f47aab843de668d5f5ffbc53d6e45Mark Andrews Unix style: # to end of line
96c17c5ecb012028ad9d66f93a252994c6ed035cMark Andrews<p><code class="filename">rndc.conf</code> is much simpler than
96c17c5ecb012028ad9d66f93a252994c6ed035cMark Andrews <code class="filename">named.conf</code>. The file uses three
98922b2b2b024dcca25be7c220cf3b16b1e6c4b5Evan Hunt statements: an options statement, a server statement
98922b2b2b024dcca25be7c220cf3b16b1e6c4b5Evan Hunt and a key statement.
98922b2b2b024dcca25be7c220cf3b16b1e6c4b5Evan Hunt The <code class="option">options</code> statement contains five clauses.
98922b2b2b024dcca25be7c220cf3b16b1e6c4b5Evan Hunt The <code class="option">default-server</code> clause is followed by the
98922b2b2b024dcca25be7c220cf3b16b1e6c4b5Evan Hunt name or address of a name server. This host will be used when
3a01ded15da064de23124e5d1a89143eceec5523Evan Hunt no name server is given as an argument to
3a01ded15da064de23124e5d1a89143eceec5523Evan Hunt <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
3a01ded15da064de23124e5d1a89143eceec5523Evan Hunt clause is followed by the name of a key which is identified by
0072ae822d966550f7c0956ed22184ec20e98f34Mark Andrews a <code class="option">key</code> statement. If no
0072ae822d966550f7c0956ed22184ec20e98f34Mark Andrews <code class="option">keyid</code> is provided on the rndc command line,
0072ae822d966550f7c0956ed22184ec20e98f34Mark Andrews and no <code class="option">key</code> clause is found in a matching
0072ae822d966550f7c0956ed22184ec20e98f34Mark Andrews <code class="option">server</code> statement, this default key will be
9e39bafd2ef3e52719b5f16aec077c7885e7e1f1Mark Andrews used to authenticate the server's commands and responses. The
9e39bafd2ef3e52719b5f16aec077c7885e7e1f1Mark Andrews <code class="option">default-port</code> clause is followed by the port
02a5e3ed85cbfc099874bb34e5901537399b5e24Mark Andrews to connect to on the remote name server. If no
02a5e3ed85cbfc099874bb34e5901537399b5e24Mark Andrews <code class="option">port</code> option is provided on the rndc command
02a5e3ed85cbfc099874bb34e5901537399b5e24Mark Andrews line, and no <code class="option">port</code> clause is found in a
bce9696c7ac65792469b29ce0ad13564953b62caEvan Hunt matching <code class="option">server</code> statement, this default port
bce9696c7ac65792469b29ce0ad13564953b62caEvan Hunt will be used to connect.
bce9696c7ac65792469b29ce0ad13564953b62caEvan Hunt The <code class="option">default-source-address</code> and
bce9696c7ac65792469b29ce0ad13564953b62caEvan Hunt <code class="option">default-source-address-v6</code> clauses which
edd82b2ce275d513fb2799b90ec464f434880e87Mark Andrews can be used to set the IPv4 and IPv6 source addresses
edd82b2ce275d513fb2799b90ec464f434880e87Mark Andrews respectively.
86856f4f3069bb2d75851b56401ffde18f41198fMark Andrews After the <code class="option">server</code> keyword, the server
86856f4f3069bb2d75851b56401ffde18f41198fMark Andrews statement includes a string which is the hostname or address
83eecff731c1a049b12f01fb699fa15ab7ddac2eEvan Hunt for a name server. The statement has three possible clauses:
83eecff731c1a049b12f01fb699fa15ab7ddac2eEvan Hunt <code class="option">key</code>, <code class="option">port</code> and
83eecff731c1a049b12f01fb699fa15ab7ddac2eEvan Hunt <code class="option">addresses</code>. The key name must match the
83eecff731c1a049b12f01fb699fa15ab7ddac2eEvan Hunt name of a key statement in the file. The port number
16134801ce8fffbb6c42bb54d544c3397a45ad06Mark Andrews specifies the port to connect to. If an <code class="option">addresses</code>
7da74ea46df30a7431441a3b8adf5134dab5067eJeremy C. Reed clause is supplied these addresses will be used instead of
64584aa0980625f834fa148dc3c95ab714efe703Evan Hunt the server name. Each address can take a optional port.
64584aa0980625f834fa148dc3c95ab714efe703Evan Hunt If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
16134801ce8fffbb6c42bb54d544c3397a45ad06Mark Andrews of supplied then these will be used to specify the IPv4 and IPv6
64584aa0980625f834fa148dc3c95ab714efe703Evan Hunt source addresses respectively.
d7b9756a214030b0022ce791b67b12fb7bceeea0Evan Hunt The <code class="option">key</code> statement begins with an identifying
d7b9756a214030b0022ce791b67b12fb7bceeea0Evan Hunt string, the name of the key. The statement has two clauses.
4357e13a4bc2e175d73b20f9ef3e809b3e269ee4Evan Hunt <code class="option">algorithm</code> identifies the encryption algorithm
4357e13a4bc2e175d73b20f9ef3e809b3e269ee4Evan Hunt for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
fd75aaa2b9816703fda5e8b2cd071a3ec7387a08Evan Hunt supported. This is followed by a secret clause which contains
7e2e41df676e1e19186242afd88a6794e37a9becMark Andrews the base-64 encoding of the algorithm's encryption key. The
7f5bdf7f4063c2fefb18900468d2c851f8de7816Evan Hunt base-64 string is enclosed in double quotes.
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt There are two common ways to generate the base-64 string for the
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
1361e038900701e126213261c0a1178025ae5a72Tinderbox User be used to generate a random key, or the
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <span><strong class="command">mmencode</strong></span> program, also known as
35f6a21f5f8114542c050bfcb484b39ce513d4bdEvan Hunt <span><strong class="command">mimencode</strong></span>, can be used to generate a
6a3fa181d1253db5191139e20231512eebaddeebEvan Hunt string from known input. <span><strong class="command">mmencode</strong></span> does
6a3fa181d1253db5191139e20231512eebaddeebEvan Hunt ship with BIND 9 but is available on many systems. See the
6a3fa181d1253db5191139e20231512eebaddeebEvan Hunt EXAMPLE section for sample command lines for each.
b5f6271f4daf1e54501af2cb7dd278d7e8003d65Mark Andrews default-server localhost;
64584aa0980625f834fa148dc3c95ab714efe703Evan Hunt default-key samplekey;
1361e038900701e126213261c0a1178025ae5a72Tinderbox User server localhost {
1361e038900701e126213261c0a1178025ae5a72Tinderbox User key samplekey;
1361e038900701e126213261c0a1178025ae5a72Tinderbox User server testserver {
38eabfcee7a9f206c268834ab9cb6d3408a31380Mark Andrews key testkey;
38eabfcee7a9f206c268834ab9cb6d3408a31380Mark Andrews addresses { localhost port 5353; };
51143259789034ac19e12984a8390b9f86ab368cMark Andrews key samplekey {
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt algorithm hmac-md5;
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt key testkey {
14bf4702f37cc707ede64a097f7d4aa671265492Evan Hunt algorithm hmac-md5;
14bf4702f37cc707ede64a097f7d4aa671265492Evan Hunt secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
2729aea3c1a720269aaae92ce3a84af1ba0a75ebMark Andrews In the above example, <span><strong class="command">rndc</strong></span> will by
a1271e2404dd42fcc477974bd0a190224f34f5f7Mark Andrews the server at localhost (127.0.0.1) and the key called samplekey.
a1271e2404dd42fcc477974bd0a190224f34f5f7Mark Andrews Commands to the localhost server will use the samplekey key, which
842a3e6d0eb745e34a3cc3e19c8c39b9492ac739Evan Hunt must also be defined in the server's configuration file with the
842a3e6d0eb745e34a3cc3e19c8c39b9492ac739Evan Hunt same name and secret. The key statement indicates that samplekey
842a3e6d0eb745e34a3cc3e19c8c39b9492ac739Evan Hunt uses the HMAC-MD5 algorithm and its secret clause contains the
1124950b35ae05a12e804e670607fe5ba775cb4aTinderbox User base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
dbb012765c735ee0d82dedb116cdc7cf18957814Evan Hunt If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
d7729155dff87d3c7a2b9103bf6e5164ea4d7dd7Mark Andrews connect to server on localhost port 5353 using the key testkey.
62ec9fd1681ffae7d6b0d54618599ecf650e3100Mark Andrews To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
850b5e80930907e4747347201dc41e4d04e036f8Mark Andrews<p><strong class="userinput"><code>rndc-confgen</code></strong>
62ec9fd1681ffae7d6b0d54618599ecf650e3100Mark Andrews A complete <code class="filename">rndc.conf</code> file, including
41e55d04032c0eefd39d74ffb73657b04fb821ecEvan Hunt randomly generated key, will be written to the standard
41e55d04032c0eefd39d74ffb73657b04fb821ecEvan Hunt output. Commented out <code class="option">key</code> and
166341d55424ca522eb456a1c7d0211e391f1ac8Evan Hunt <code class="option">controls</code> statements for
166341d55424ca522eb456a1c7d0211e391f1ac8Evan Hunt <code class="filename">named.conf</code> are also printed.
166341d55424ca522eb456a1c7d0211e391f1ac8Evan Hunt To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
166341d55424ca522eb456a1c7d0211e391f1ac8Evan Hunt<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt<a name="id2605399"></a><h2>NAME SERVER CONFIGURATION</h2>
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt The name server must be configured to accept rndc connections and
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt to recognize the key specified in the <code class="filename">rndc.conf</code>
c41d8a22ab5f4a487f4c16b78f23792f78a3a851Francis Dupont file, using the controls statement in <code class="filename">named.conf</code>.
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt See the sections on the <code class="option">controls</code> statement in the
a165a17a81ff3285f4f4d79785fafb465e626183Evan Hunt BIND 9 Administrator Reference Manual for details.
e5f9fa7e18d50569a7d723acbb6f641e13ed3787Evan Hunt<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
e5f9fa7e18d50569a7d723acbb6f641e13ed3787Evan Hunt <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
e5f9fa7e18d50569a7d723acbb6f641e13ed3787Evan Hunt <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
62cce60a15990bf8ec05b4234a5c965a5a8e86c0Evan Hunt <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
e2d635d630f6f61fefd3d4475c45b097b16b8a2aEvan Hunt<p><span class="corpauthor">Internet Systems Consortium</span>
3249da26fc28297265d444a1f3647f1e6700a2a0Evan Hunt<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
3249da26fc28297265d444a1f3647f1e6700a2a0Evan Hunt<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
3249da26fc28297265d444a1f3647f1e6700a2a0Evan Hunt<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
47c847e286ac1d9dcc1b6dec5430ad9d2abad7b2Evan Hunt<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
63add83a2699aac4e01be6d1f2d093cfed4f744aMark Andrews<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>