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