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