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