man.rndc.conf.html revision b0e8629055a766d4555a005a283c2889a5974945
e2cc7418bf895d22854d84590b63905fac0d4b90Mark Andrews - Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
36ec0d374836d070ba05b495e6f0a27f60e94476Evan Hunt - Copyright (C) 2000-2003 Internet Software Consortium.
36ec0d374836d070ba05b495e6f0a27f60e94476Evan Hunt - Permission to use, copy, modify, and distribute this software for any
e446fd29b9c6c4a7b6b5bb0aee3932578c346718Mukund Sivaraman - purpose with or without fee is hereby granted, provided that the above
f896f7c8be894a737998b97008a1389e72972fcfMukund Sivaraman - copyright notice and this permission notice appear in all copies.
027a4a5b5d806290146ce4989d34be2c8a664e8cMukund Sivaraman - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
027a4a5b5d806290146ce4989d34be2c8a664e8cMukund Sivaraman - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
b5252fcde512405a68dd4becfe683d9763bd0feaMukund Sivaraman - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
b5252fcde512405a68dd4becfe683d9763bd0feaMukund Sivaraman - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
b5252fcde512405a68dd4becfe683d9763bd0feaMukund Sivaraman - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
b5252fcde512405a68dd4becfe683d9763bd0feaMukund Sivaraman - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
b5252fcde512405a68dd4becfe683d9763bd0feaMukund Sivaraman - PERFORMANCE OF THIS SOFTWARE.
99056063905a9273ec59cf477ae747e0490182b7Mukund Sivaraman<!-- $Id: man.rndc.conf.html,v 1.43 2007/01/30 00:25:00 marka Exp $ -->
62f2fefaec754e6a4841ff0e72726e6c0cd89c86Michał Kępień<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
62f2fefaec754e6a4841ff0e72726e6c0cd89c86Michał Kępień<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
b351a5864727a390e06d787e522b141ca760590fMichał Kępień<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
b351a5864727a390e06d787e522b141ca760590fMichał Kępień<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
b351a5864727a390e06d787e522b141ca760590fMichał Kępień<link rel="prev" href="man.rndc.html" title="rndc">
b351a5864727a390e06d787e522b141ca760590fMichał Kępień<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
b351a5864727a390e06d787e522b141ca760590fMichał Kępień<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
8008de0b11bacb3de3a1016c8c0a46f3c0653184Mark Andrews<table width="100%" summary="Navigation header">
8008de0b11bacb3de3a1016c8c0a46f3c0653184Mark Andrews<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
8008de0b11bacb3de3a1016c8c0a46f3c0653184Mark Andrews<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
7b4bfc0201ffbcd64a336b99c945891808c44af0Mark Andrews<th width="60%" align="center">Manual pages</th>
7b4bfc0201ffbcd64a336b99c945891808c44af0Mark Andrews<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
a2a0100e0fc73c0af67a7c9e3524816954448dc6Evan Hunt<a name="man.rndc.conf"></a><div class="titlepage"></div>
a2a0100e0fc73c0af67a7c9e3524816954448dc6Evan Hunt<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
22bed621ef87bc8b6c1fea599b02c4b38dd6bf48Mark Andrews<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
e5f5675b1da287ed40aeff081ad2af86090e8d17Evan Hunt<p><code class="filename">rndc.conf</code> is the configuration file
e5f5675b1da287ed40aeff081ad2af86090e8d17Evan Hunt for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
29f0ced781d745591fd058e530a68a281cd7a510Evan Hunt utility. This file has a similar structure and syntax to
29f0ced781d745591fd058e530a68a281cd7a510Evan Hunt <code class="filename">named.conf</code>. Statements are enclosed
29f0ced781d745591fd058e530a68a281cd7a510Evan Hunt in braces and terminated with a semi-colon. Clauses in
b9fd54f8d4572fe5dcaf9d4b74f6ecb8027cc450Evan Hunt the statements are also semi-colon terminated. The usual
b9fd54f8d4572fe5dcaf9d4b74f6ecb8027cc450Evan Hunt comment styles are supported:
fcb5e646e4d775539e348fa21ba13307f2695bf5Mark Andrews C style: /* */
a22c3cf51567651f74aee5c263c597b8d752c2ccMichał Kępień C++ style: // to end of line
b301c4293c082fcce4ec26218e6fad346976eb9eMark Andrews Unix style: # to end of line
b301c4293c082fcce4ec26218e6fad346976eb9eMark Andrews<p><code class="filename">rndc.conf</code> is much simpler than
5c4e0c7800b5c7783e7f8b9ce80a6f8dc47f8856Mark Andrews <code class="filename">named.conf</code>. The file uses three
5c4e0c7800b5c7783e7f8b9ce80a6f8dc47f8856Mark Andrews statements: an options statement, a server statement
5c4e0c7800b5c7783e7f8b9ce80a6f8dc47f8856Mark Andrews and a key statement.
6e1f755f19ef244422e1efa4551fe23775e1a38cMark Andrews The <code class="option">options</code> statement contains five clauses.
435a7cd2293dfa9264678508762ab9acb8d41e50Mark Andrews The <code class="option">default-server</code> clause is followed by the
435a7cd2293dfa9264678508762ab9acb8d41e50Mark Andrews name or address of a name server. This host will be used when
435a7cd2293dfa9264678508762ab9acb8d41e50Mark Andrews no name server is given as an argument to
b7a823a402eb5c4e99f283e58d778a903d2e72f5Michał Kępień <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
b7a823a402eb5c4e99f283e58d778a903d2e72f5Michał Kępień clause is followed by the name of a key which is identified by
b7a823a402eb5c4e99f283e58d778a903d2e72f5Michał Kępień a <code class="option">key</code> statement. If no
c46c8e5c56ec4e81a39632e0036f20a6a3c18b8bMark Andrews <code class="option">keyid</code> is provided on the rndc command line,
031bc55634f443c7c70fbf44c6ac6d8abe72f22bEvan Hunt and no <code class="option">key</code> clause is found in a matching
031bc55634f443c7c70fbf44c6ac6d8abe72f22bEvan Hunt <code class="option">server</code> statement, this default key will be
031bc55634f443c7c70fbf44c6ac6d8abe72f22bEvan Hunt used to authenticate the server's commands and responses. The
a64daf673deff2358a91bee26bbf2bf874f47c6eMark Andrews <code class="option">default-port</code> clause is followed by the port
a64daf673deff2358a91bee26bbf2bf874f47c6eMark Andrews to connect to on the remote name server. If no
a64daf673deff2358a91bee26bbf2bf874f47c6eMark Andrews <code class="option">port</code> option is provided on the rndc command
0aadc6dd7b719539445e7a0a058b15dd9d982a9bMichał Kępień line, and no <code class="option">port</code> clause is found in a
0aadc6dd7b719539445e7a0a058b15dd9d982a9bMichał Kępień matching <code class="option">server</code> statement, this default port
0aadc6dd7b719539445e7a0a058b15dd9d982a9bMichał Kępień will be used to connect.
0aadc6dd7b719539445e7a0a058b15dd9d982a9bMichał Kępień The <code class="option">default-source-address</code> and
0aadc6dd7b719539445e7a0a058b15dd9d982a9bMichał Kępień <code class="option">default-source-address-v6</code> clauses which
f20ff8b74d21fa3e3f071544f6fd060d015cf27eMichał Kępień can be used to set the IPv4 and IPv6 source addresses
f20ff8b74d21fa3e3f071544f6fd060d015cf27eMichał Kępień respectively.
7ff682f3c628d785048bbe0242e6a32ea26c6747Michał Kępień After the <code class="option">server</code> keyword, the server
7ff682f3c628d785048bbe0242e6a32ea26c6747Michał Kępień statement includes a string which is the hostname or address
7ff682f3c628d785048bbe0242e6a32ea26c6747Michał Kępień for a name server. The statement has three possible clauses:
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień <code class="option">key</code>, <code class="option">port</code> and
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień <code class="option">addresses</code>. The key name must match the
e02fa56849131911e9554133b17a5325b37d0828Michał Kępień name of a key statement in the file. The port number
abcea74291c37abf68be4e06997c59e5494f06adMark Andrews specifies the port to connect to. If an <code class="option">addresses</code>
abcea74291c37abf68be4e06997c59e5494f06adMark Andrews clause is supplied these addresses will be used instead of
abcea74291c37abf68be4e06997c59e5494f06adMark Andrews the server name. Each address can take a optional port.
d748d8a4afc200800f6289683361a393b15ba6bfMichał Kępień If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
d748d8a4afc200800f6289683361a393b15ba6bfMichał Kępień of supplied then these will be used to specify the IPv4 and IPv6
d748d8a4afc200800f6289683361a393b15ba6bfMichał Kępień source addresses respectively.
cbb33c87f4bcf415c840acb61c9d4642c3c2a8e0Michał Kępień The <code class="option">key</code> statement begins with an identifying
324b00ad4950b00346f5ba2382a51709bd82afe9Mark Andrews string, the name of the key. The statement has two clauses.
324b00ad4950b00346f5ba2382a51709bd82afe9Mark Andrews <code class="option">algorithm</code> identifies the encryption algorithm
296f5969a8dd6e3d1bb3761569c6a7070abd2e47Tinderbox User for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
4dc6fa1e92af7a62875b6f6f2931beefd58cb4faEvan Hunt supported. This is followed by a secret clause which contains
4dc6fa1e92af7a62875b6f6f2931beefd58cb4faEvan Hunt the base-64 encoding of the algorithm's encryption key. The
b81b178ab919bdbd92021cfc7e6e8d971cd38e83Mark Andrews base-64 string is enclosed in double quotes.
bf216589c1a81e4431653a145b252b6ce367d7cdMark Andrews There are two common ways to generate the base-64 string for the
bf216589c1a81e4431653a145b252b6ce367d7cdMark Andrews secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
7dbeb5e7f067585abfb12fac314a0d2a8f0dd040Evan Hunt be used to generate a random key, or the
6e10f87913db176724e89b52e686b0992898da75Mukund Sivaraman <span><strong class="command">mmencode</strong></span> program, also known as
6e10f87913db176724e89b52e686b0992898da75Mukund Sivaraman <span><strong class="command">mimencode</strong></span>, can be used to generate a
6e10f87913db176724e89b52e686b0992898da75Mukund Sivaraman string from known input. <span><strong class="command">mmencode</strong></span> does
37f6466aa327a5b444e41c8cb57ab5caacfe6279Evan Hunt ship with BIND 9 but is available on many systems. See the
37f6466aa327a5b444e41c8cb57ab5caacfe6279Evan Hunt EXAMPLE section for sample command lines for each.
ce6f0c122140647b5652c0d4de523c994fcfea08Michał Kępień default-server localhost;
f72f5879424ce4081893b306b8c31f29fe9205e0Evan Hunt default-key samplekey;
1073e2001caee13cc1fa52de97feddd633d50fd8Evan Hunt server localhost {
1073e2001caee13cc1fa52de97feddd633d50fd8Evan Hunt key samplekey;
11c4e6d8fcc9bc148543c1ee632315e096d2bcf2Michał Kępień server testserver {
59122481b2aa65de4518677c6949f03711d2553aEvan Hunt key testkey;
59122481b2aa65de4518677c6949f03711d2553aEvan Hunt addresses { localhost port 5353; };
fe6d2fd8338d6f6ac4c79bea9a8daad903460040Evan Hunt key samplekey {
05a456499af940762d6658366abafb220c5053ccMark Andrews algorithm hmac-md5;
05a456499af940762d6658366abafb220c5053ccMark Andrews secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
e3efc855f9f0acc9b14bb8e9c833e0fa209068b6Mark Andrews key testkey {
e3efc855f9f0acc9b14bb8e9c833e0fa209068b6Mark Andrews algorithm hmac-md5;
e3efc855f9f0acc9b14bb8e9c833e0fa209068b6Mark Andrews secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
6727802528c27484e0d36d70f0b936022d3226e3Michał Kępień In the above example, <span><strong class="command">rndc</strong></span> will by
4d41be5f9e86c11a6f00e2b005cfc5abae2c1ab3Mark Andrews the server at localhost (127.0.0.1) and the key called samplekey.
4d41be5f9e86c11a6f00e2b005cfc5abae2c1ab3Mark Andrews Commands to the localhost server will use the samplekey key, which
bfde61d5194a534d800f3b90008d1f52261922c5Mark Andrews must also be defined in the server's configuration file with the
bfde61d5194a534d800f3b90008d1f52261922c5Mark Andrews same name and secret. The key statement indicates that samplekey
bfde61d5194a534d800f3b90008d1f52261922c5Mark Andrews uses the HMAC-MD5 algorithm and its secret clause contains the
42ae02626d05921ca7508ae6f9c48ea699596bc6Mark Andrews base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
42ae02626d05921ca7508ae6f9c48ea699596bc6Mark Andrews If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
41caed6e2d7e9caace30e6c59f199ab6bd438f01Mark Andrews connect to server on localhost port 5353 using the key testkey.
28ea558bc80f75e46d77ea0533232bb9d4e644f7Mark Andrews To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
28ea558bc80f75e46d77ea0533232bb9d4e644f7Mark Andrews<p><strong class="userinput"><code>rndc-confgen</code></strong>
565535d1820c63c64ec3c89e1f4815c326aed7aeEvan Hunt A complete <code class="filename">rndc.conf</code> file, including
6045abbc9a0d7d449a13b6fbfbf32d419b6bee96Mark Andrews randomly generated key, will be written to the standard
f7d148398ca4511551c737e655b15f7d0d59a783Mark Andrews output. Commented out <code class="option">key</code> and
f7d148398ca4511551c737e655b15f7d0d59a783Mark Andrews <code class="option">controls</code> statements for
f7d148398ca4511551c737e655b15f7d0d59a783Mark Andrews <code class="filename">named.conf</code> are also printed.
3a84275b10ab16965e86f6ca97e70c1bdca885a0Mark Andrews To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
398834f7559617bdfd6c10ba555609a2f306e3d4Mark Andrews<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
398834f7559617bdfd6c10ba555609a2f306e3d4Mark Andrews<a name="id2604981"></a><h2>NAME SERVER CONFIGURATION</h2>
28061f80b698171892e81c0856bc722190947998Evan Hunt The name server must be configured to accept rndc connections and
28061f80b698171892e81c0856bc722190947998Evan Hunt to recognize the key specified in the <code class="filename">rndc.conf</code>
a785bf2c39c6f223a93c27bbff81591b38095577Mark Andrews file, using the controls statement in <code class="filename">named.conf</code>.
a785bf2c39c6f223a93c27bbff81591b38095577Mark Andrews See the sections on the <code class="option">controls</code> statement in the
a03f4b1ea4f1a4a70963fbeb606841c217f9e5f3Evan Hunt BIND 9 Administrator Reference Manual for details.
d315545e6db6792692fe2dcb788ac6717a33b75fEvan Hunt<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
d315545e6db6792692fe2dcb788ac6717a33b75fEvan Hunt <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
d315545e6db6792692fe2dcb788ac6717a33b75fEvan Hunt <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
00f131293520b70728cd48840e09953fa45a745bMark Andrews <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
b2e71853060a384070d422afda6d1c692ff608e3Mark Andrews<p><span class="corpauthor">Internet Systems Consortium</span>
dd5375de0a7a515ee4fb2fd217e9577259d38c07Mark Andrews<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
dd5375de0a7a515ee4fb2fd217e9577259d38c07Mark Andrews<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
3a58e1fefb0a9fd5dab11f271a320c6b90473f76Mukund Sivaraman<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
5aed5dc329a2bf1340e9ff2256c1cf4e3005ea0bMark Andrews<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
5aed5dc329a2bf1340e9ff2256c1cf4e3005ea0bMark Andrews<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>