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