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