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