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