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