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