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