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