man.rndc.conf.html revision 057cafaa3df7be7a6dcca71fbaf8fb498fd83518
59602f2a7c4e4809941583bed3e94cd26e628f1aTinderbox User - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2000-2003 Internet Software Consortium.
19558a04decde0e7261d489d92d04ad88104217bTinderbox User - Permission to use, copy, modify, and distribute this software for any
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews - purpose with or without fee is hereby granted, provided that the above
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews - copyright notice and this permission notice appear in all copies.
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
287a6a8f9040dc43560cd69cddf83bfc0f53b76fTinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e5a6871cd0635ecdb2bf792316a2d8c53206f4b2Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<!-- $Id: man.rndc.conf.html,v 1.7 2005/09/09 13:40:39 marka Exp $ -->
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox User<link rel="prev" href="man.rndc.html" title="rndc">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<table width="100%" summary="Navigation header">
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<th width="60%" align="center">Manual pages</th>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<a name="man.rndc.conf"></a><div class="titlepage"></div>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User<p><code class="filename">rndc.conf</code> is the configuration file
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt utility. This file has a similar structure and syntax to
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User <code class="filename">named.conf</code>. Statements are enclosed
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater in braces and terminated with a semi-colon. Clauses in
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont the statements are also semi-colon terminated. The usual
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater comment styles are supported:
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews C style: /* */
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews C++ style: // to end of line
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews Unix style: # to end of line
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<p><code class="filename">rndc.conf</code> is much simpler than
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="filename">named.conf</code>. The file uses three
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews statements: an options statement, a server statement
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews and a key statement.
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt The <code class="option">options</code> statement contains five clauses.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The <code class="option">default-server</code> clause is followed by the
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User name or address of a name server. This host will be used when
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User no name server is given as an argument to
294e9d4c34462d29a3e766c88f452b46aeb3702fTinderbox User <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User clause is followed by the name of a key which is identified by
4c6bae917bec70e1fc4d1b761a9765075af78441Tinderbox User a <code class="option">key</code> statement. If no
294e9d4c34462d29a3e766c88f452b46aeb3702fTinderbox User <code class="option">keyid</code> is provided on the rndc command line,
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt and no <code class="option">key</code> clause is found in a matching
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <code class="option">server</code> statement, this default key will be
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt used to authenticate the server's commands and responses. The
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <code class="option">default-port</code> clause is followed by the port
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt to connect to on the remote name server. If no
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <code class="option">port</code> option is provided on the rndc command
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox User line, and no <code class="option">port</code> clause is found in a
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User matching <code class="option">server</code> statement, this default port
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews will be used to connect.
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User The <code class="option">default-source-address</code> and
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User <code class="option">default-source-address-v6</code> clauses which
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews can be used to set the IPv4 and IPv6 source addresses
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User respectively.
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews After the <code class="option">server</code> keyword, the server
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews statement includes a string which is the hostname or address
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User for a name server. The statement has three possible clauses:
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">key</code>, <code class="option">port</code> and
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User <code class="option">addresses</code>. The key name must match the
aef6cf0f147a5014d4891c9689b9f463399e16e7Tinderbox User name of a key statement in the file. The port number
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews specifies the port to connect to. If an <code class="option">addresses</code>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User clause is supplied these addresses will be used instead of
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson the server name. Each address can take a optional port.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews of supplied then these will be used to specify the IPv4 and IPv6
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt source addresses respectively.
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews The <code class="option">key</code> statement begins with an identifying
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews string, the name of the key. The statement has two clauses.
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <code class="option">algorithm</code> identifies the encryption algorithm
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson supported. This is followed by a secret clause which contains
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User the base-64 encoding of the algorithm's encryption key. The
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews base-64 string is enclosed in double quotes.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User There are two common ways to generate the base-64 string for the
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews be used to generate a random key, or the
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <span><strong class="command">mmencode</strong></span> program, also known as
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <span><strong class="command">mimencode</strong></span>, can be used to generate a
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User string from known input. <span><strong class="command">mmencode</strong></span> does
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User ship with BIND 9 but is available on many systems. See the
a450977e98155f6e828fe6f8d52cf24674231831Mark Andrews EXAMPLE section for sample command lines for each.
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User default-server localhost;
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews default-key samplekey;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews server localhost {
a03cb08d0c4f1ca5fbc121d2f02bdffa7eb52286Mark Andrews key samplekey;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews server testserver {
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews key testkey;
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User addresses { localhost port 5353; };
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews key samplekey {
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User algorithm hmac-md5;
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox User secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User key testkey {
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater algorithm hmac-md5;
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User In the above example, <span><strong class="command">rndc</strong></span> will by
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt the server at localhost (127.0.0.1) and the key called samplekey.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Commands to the localhost server will use the samplekey key, which
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User must also be defined in the server's configuration file with the
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater same name and secret. The key statement indicates that samplekey
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User uses the HMAC-MD5 algorithm and its secret clause contains the
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson connect to server on localhost port 5353 using the key testkey.
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<p><strong class="userinput"><code>rndc-confgen</code></strong>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews A complete <code class="filename">rndc.conf</code> file, including
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews randomly generated key, will be written to the standard
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User output. Commented out <code class="option">key</code> and
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater <code class="option">controls</code> statements for
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <code class="filename">named.conf</code> are also printed.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<a name="id2575181"></a><h2>NAME SERVER CONFIGURATION</h2>
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User The name server must be configured to accept rndc connections and
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User to recognize the key specified in the <code class="filename">rndc.conf</code>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews file, using the controls statement in <code class="filename">named.conf</code>.
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt See the sections on the <code class="option">controls</code> statement in the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews BIND 9 Administrator Reference Manual for details.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
bac4435d473c9a0281507524f084480c34aa942aTinderbox User <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
1fce11b1d3f2d461d261156b8cdc64ab864f06a9Tinderbox User <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater<p><span class="corpauthor">Internet Systems Consortium</span>
933799f3641f4f78445d015008bad0038900a82aTinderbox User<table width="100%" summary="Navigation footer">
ac2e2800b4ac9cbe4cb756d967f4583c611eb75eMark Andrews<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
ba8b771c371967dd1254c7fa82ebe4158ee04b24Tinderbox User<td width="40%" align="left" valign="top"><span class="application">rndc</span>�</td>
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
3ec8f7777ea2b04fc1ebb63077f0916f63b1011aTinderbox User<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span></td>