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