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