man.rndc.conf.html revision 7911e6f9de303bca5a3d8b34f4330c8f7cecffae
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski - Copyright (C) 2000-2016 Internet Systems Consortium, Inc. ("ISC")
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski - This Source Code Form is subject to the terms of the Mozilla Public
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski - License, v. 2.0. If a copy of the MPL was not distributed with this
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski - file, You can obtain one at http://mozilla.org/MPL/2.0/.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<link rel="prev" href="man.rndc.html" title="rndc">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<table width="100%" summary="Navigation header">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<th width="60%" align="center">Manual pages</th>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a name="man.rndc.conf"></a><div class="titlepage"></div>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski — rndc configuration file
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a name="id-1.14.28.7"></a><h2>DESCRIPTION</h2>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <p><code class="filename">rndc.conf</code> is the configuration file
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski utility. This file has a similar structure and syntax to
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="filename">named.conf</code>. Statements are enclosed
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski in braces and terminated with a semi-colon. Clauses in
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski the statements are also semi-colon terminated. The usual
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski comment styles are supported:
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski C style: /* */
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski C++ style: // to end of line
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski Unix style: # to end of line
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <p><code class="filename">rndc.conf</code> is much simpler than
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="filename">named.conf</code>. The file uses three
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski statements: an options statement, a server statement
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski and a key statement.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski The <code class="option">options</code> statement contains five clauses.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski The <code class="option">default-server</code> clause is followed by the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski name or address of a name server. This host will be used when
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski no name server is given as an argument to
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski clause is followed by the name of a key which is identified by
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski a <code class="option">key</code> statement. If no
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">keyid</code> is provided on the rndc command line,
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski and no <code class="option">key</code> clause is found in a matching
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">server</code> statement, this default key will be
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski used to authenticate the server's commands and responses. The
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">default-port</code> clause is followed by the port
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski to connect to on the remote name server. If no
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">port</code> option is provided on the rndc command
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski line, and no <code class="option">port</code> clause is found in a
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski matching <code class="option">server</code> statement, this default port
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski will be used to connect.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski The <code class="option">default-source-address</code> and
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">default-source-address-v6</code> clauses which
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski can be used to set the IPv4 and IPv6 source addresses
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski After the <code class="option">server</code> keyword, the server
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski statement includes a string which is the hostname or address
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski for a name server. The statement has three possible clauses:
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">key</code>, <code class="option">port</code> and
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">addresses</code>. The key name must match the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski name of a key statement in the file. The port number
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski specifies the port to connect to. If an <code class="option">addresses</code>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski clause is supplied these addresses will be used instead of
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski the server name. Each address can take an optional port.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski of supplied then these will be used to specify the IPv4 and IPv6
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski source addresses respectively.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski The <code class="option">key</code> statement begins with an identifying
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski string, the name of the key. The statement has two clauses.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <code class="option">algorithm</code> identifies the authentication algorithm
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski (default), HMAC-SHA384 and HMAC-SHA512 are
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski supported. This is followed by a secret clause which contains
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski the base-64 encoding of the algorithm's authentication key. The
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski base-64 string is enclosed in double quotes.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski There are two common ways to generate the base-64 string for the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski be used to generate a random key, or the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski <span class="command"><strong>mmencode</strong></span> program, also known as
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <span class="command"><strong>mimencode</strong></span>, can be used to generate a
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski string from known input. <span class="command"><strong>mmencode</strong></span> does
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski ship with BIND 9 but is available on many systems. See the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski EXAMPLE section for sample command lines for each.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a name="id-1.14.28.8"></a><h2>EXAMPLE</h2>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski default-server localhost;
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski default-key samplekey;
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski server localhost {
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski key samplekey;
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski server testserver {
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski addresses { localhost port 5353; };
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski key samplekey {
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski algorithm hmac-sha256;
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski algorithm hmac-sha256;
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski In the above example, <span class="command"><strong>rndc</strong></span> will by
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski the server at localhost (127.0.0.1) and the key called samplekey.
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski Commands to the localhost server will use the samplekey key, which
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski must also be defined in the server's configuration file with the
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski same name and secret. The key statement indicates that samplekey
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski uses the HMAC-SHA256 algorithm and its secret clause contains the
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski connect to server on localhost port 5353 using the key testkey.
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <p><strong class="userinput"><code>rndc-confgen</code></strong>
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski A complete <code class="filename">rndc.conf</code> file, including
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski randomly generated key, will be written to the standard
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski output. Commented-out <code class="option">key</code> and
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <code class="option">controls</code> statements for
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <code class="filename">named.conf</code> are also printed.
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a name="id-1.14.28.9"></a><h2>NAME SERVER CONFIGURATION</h2>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski The name server must be configured to accept rndc connections and
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski to recognize the key specified in the <code class="filename">rndc.conf</code>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski file, using the controls statement in <code class="filename">named.conf</code>.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski See the sections on the <code class="option">controls</code> statement in the
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski BIND 9 Administrator Reference Manual for details.
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski<a name="id-1.14.28.10"></a><h2>SEE ALSO</h2>
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <span class="refentrytitle">rndc</span>(8)
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <span class="refentrytitle">rndc-confgen</span>(8)
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <span class="refentrytitle">mmencode</span>(1)
b54fcbf691761f7356ee5239114b8a0adf292cc3Tomasz Boczkowski <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<table width="100%" summary="Navigation footer">
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<span class="application">rndc</span>�</td>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>
6f195ddf891afcc5029baa42fe2007ea923776c0Tomasz Boczkowski<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.0</p>