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