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