man.rndc.conf.html revision d6fa26d0adaec6c910115be34fe7a5a5f402c14f
a4544a5a0e622ef69e38641f87ab1b5685e05911Phill Cunnington<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster - Copyright (C) 2000-2015 Internet Systems Consortium, Inc. ("ISC")
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster - This Source Code Form is subject to the terms of the Mozilla Public
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster - License, v. 2.0. If a copy of the MPL was not distributed with this
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster - file, You can obtain one at http://mozilla.org/MPL/2.0/.
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">
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<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>
c9ba1a8f3afcf43e26fe5b062ac652b347b283fbJames Phillpotts<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>
c9ba1a8f3afcf43e26fe5b062ac652b347b283fbJames Phillpotts<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
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott 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
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford Unix style: # to end of line
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott<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>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster 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
ecb73e63056eb80738d8460818f1a742f515de1cPeter Major <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.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott After the <code class="option">server</code> keyword, the server
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford 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
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford (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
ecb73e63056eb80738d8460818f1a742f515de1cPeter Major string from known input. <span class="command"><strong>mmencode</strong></span> does
ecb73e63056eb80738d8460818f1a742f515de1cPeter Major 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; };
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford key samplekey {
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford algorithm hmac-sha256;
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster key testkey {
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster algorithm hmac-sha256;
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster In the above example, <span class="command"><strong>rndc</strong></span> will by
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford 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.
c9ba1a8f3afcf43e26fe5b062ac652b347b283fbJames Phillpotts To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
c9ba1a8f3afcf43e26fe5b062ac652b347b283fbJames Phillpotts<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.
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford 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.28.9"></a><h2>NAME SERVER CONFIGURATION</h2>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster The name server must be configured to accept rndc connections and
c42550c0e86e2c3f821f5e754ea8ba52d8bb5427Tony Bamford 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>,
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td>
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>
d5945925e5fd8d1d286fa82f1fda99938dd3cbe2Peter Major<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.0rc1</p>