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