man.rndc.conf.html revision 78ec962d9828200d18cd0e41b7d6b9792a74923d
28d9fd53819cc163629c867466b20d8ebcae8842David Lawrence - Copyright (C) 2004-2014 Internet Systems Consortium, Inc. ("ISC")
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - Copyright (C) 2000-2003 Internet Software Consortium.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews - Permission to use, copy, modify, and/or distribute this software for any
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews - purpose with or without fee is hereby granted, provided that the above
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - copyright notice and this permission notice appear in all copies.
15a44745412679c30a6d022733925af70a38b715David Lawrence - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
15a44745412679c30a6d022733925af70a38b715David Lawrence - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
15a44745412679c30a6d022733925af70a38b715David Lawrence - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15a44745412679c30a6d022733925af70a38b715David Lawrence - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15a44745412679c30a6d022733925af70a38b715David Lawrence - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15a44745412679c30a6d022733925af70a38b715David Lawrence - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15a44745412679c30a6d022733925af70a38b715David Lawrence - PERFORMANCE OF THIS SOFTWARE.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<!-- $Id$ -->
659c68b446073e4e450dd2021fdb5bc40decffe2David Lawrence<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
854d0238dbc2908490197984b3b9d558008a53dfMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
854d0238dbc2908490197984b3b9d558008a53dfMark Andrews<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
6324997211a5e2d82528dcde98e8981190a35faeMichael Graff<link rel="prev" href="man.rndc.html" title="rndc">
6324997211a5e2d82528dcde98e8981190a35faeMichael Graff<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<table width="100%" summary="Navigation header">
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
f7b99290c31abeb20c55fc55391510450ce60423Mark Andrews<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
659c68b446073e4e450dd2021fdb5bc40decffe2David Lawrence<th width="60%" align="center">Manual pages</th>
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<a name="man.rndc.conf"></a><div class="titlepage"></div>
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews<p><code class="filename">rndc.conf</code> is the configuration file
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews utility. This file has a similar structure and syntax to
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="filename">named.conf</code>. Statements are enclosed
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews in braces and terminated with a semi-colon. Clauses in
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews the statements are also semi-colon terminated. The usual
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews comment styles are supported:
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews C style: /* */
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews C++ style: // to end of line
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews Unix style: # to end of line
3d5cad69ec20157912e95cf3b79316dfb0a314f3Mark Andrews<p><code class="filename">rndc.conf</code> is much simpler than
f7b99290c31abeb20c55fc55391510450ce60423Mark Andrews <code class="filename">named.conf</code>. The file uses three
659c68b446073e4e450dd2021fdb5bc40decffe2David Lawrence statements: an options statement, a server statement
1ef8965366d91e02a4672c35a187d30aa4a4c72cMark Andrews and a key statement.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews The <code class="option">options</code> statement contains five clauses.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews The <code class="option">default-server</code> clause is followed by the
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews name or address of a name server. This host will be used when
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews no name server is given as an argument to
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence clause is followed by the name of a key which is identified by
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews a <code class="option">key</code> statement. If no
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">keyid</code> is provided on the rndc command line,
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews and no <code class="option">key</code> clause is found in a matching
3d5cad69ec20157912e95cf3b79316dfb0a314f3Mark Andrews <code class="option">server</code> statement, this default key will be
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews used to authenticate the server's commands and responses. The
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">default-port</code> clause is followed by the port
94a08e09db3dc844b6ee4841c368a2d7074a9c3fAndreas Gustafsson to connect to on the remote name server. If no
52637f592f705ca93fadc218e403fd55e8ce4aeaMark Andrews <code class="option">port</code> option is provided on the rndc command
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews line, and no <code class="option">port</code> clause is found in a
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews matching <code class="option">server</code> statement, this default port
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews will be used to connect.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews The <code class="option">default-source-address</code> and
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">default-source-address-v6</code> clauses which
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews can be used to set the IPv4 and IPv6 source addresses
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews respectively.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews After the <code class="option">server</code> keyword, the server
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews statement includes a string which is the hostname or address
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews for a name server. The statement has three possible clauses:
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">key</code>, <code class="option">port</code> and
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">addresses</code>. The key name must match the
3d5cad69ec20157912e95cf3b79316dfb0a314f3Mark Andrews name of a key statement in the file. The port number
d981ca645597116d227a48bf37cc5edc061c854dBob Halley specifies the port to connect to. If an <code class="option">addresses</code>
3d5cad69ec20157912e95cf3b79316dfb0a314f3Mark Andrews clause is supplied these addresses will be used instead of
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews the server name. Each address can take an optional port.
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
f7b99290c31abeb20c55fc55391510450ce60423Mark Andrews of supplied then these will be used to specify the IPv4 and IPv6
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews source addresses respectively.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews The <code class="option">key</code> statement begins with an identifying
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews string, the name of the key. The statement has two clauses.
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews <code class="option">algorithm</code> identifies the authentication algorithm
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews (default), HMAC-SHA384 and HMAC-SHA512 are
7c0539bea56022274da04263eb41fbb5b8835c38Mark Andrews supported. This is followed by a secret clause which contains
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews the base-64 encoding of the algorithm's authentication key. The
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews base-64 string is enclosed in double quotes.
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews There are two common ways to generate the base-64 string for the
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews be used to generate a random key, or the
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews <span><strong class="command">mmencode</strong></span> program, also known as
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews <span><strong class="command">mimencode</strong></span>, can be used to generate a
5d51e67c3b4f35c1be742574aacc1d88fe6ed444Mark Andrews string from known input. <span><strong class="command">mmencode</strong></span> does
63cef8bde8b92aeb30ccdcf21d4e44c9be9cc6e3Andreas Gustafsson ship with BIND 9 but is available on many systems. See the
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews EXAMPLE section for sample command lines for each.
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews default-server localhost;
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews default-key samplekey;
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews server localhost {
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews key samplekey;
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews server testserver {
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews key testkey;
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews addresses { localhost port 5353; };
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews key samplekey {
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews algorithm hmac-sha256;
94a3bcd132e515b4baa0884ba9dd0f361d2e17bcMark Andrews secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
9281e7aa775026dc47c01745fdcc438645146877Mark Andrews key testkey {
94a3bcd132e515b4baa0884ba9dd0f361d2e17bcMark Andrews algorithm hmac-sha256;
d981ca645597116d227a48bf37cc5edc061c854dBob Halley secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
659c68b446073e4e450dd2021fdb5bc40decffe2David Lawrence In the above example, <span><strong class="command">rndc</strong></span> will by
d981ca645597116d227a48bf37cc5edc061c854dBob Halley the server at localhost (127.0.0.1) and the key called samplekey.
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael Graff Commands to the localhost server will use the samplekey key, which
d981ca645597116d227a48bf37cc5edc061c854dBob Halley must also be defined in the server's configuration file with the
d981ca645597116d227a48bf37cc5edc061c854dBob Halley same name and secret. The key statement indicates that samplekey
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff uses the HMAC-SHA256 algorithm and its secret clause contains the
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley connect to server on localhost port 5353 using the key testkey.
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley<p><strong class="userinput"><code>rndc-confgen</code></strong>
e27a69f8bd9538e08f775265167ba6cc5f47c587Bob Halley A complete <code class="filename">rndc.conf</code> file, including