man.rndc.conf.html revision d6fa26d0adaec6c910115be34fe7a5a5f402c14f
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000-2015 Internet Systems Consortium, Inc. ("ISC")
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence - This Source Code Form is subject to the terms of the Mozilla Public
5fbced719b71e659322b4ce3e4a39c9b039674c7Bob Halley - License, v. 2.0. If a copy of the MPL was not distributed with this
5fbced719b71e659322b4ce3e4a39c9b039674c7Bob Halley - file, You can obtain one at http://mozilla.org/MPL/2.0/.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<link rel="prev" href="man.rndc.html" title="rndc">
15a44745412679c30a6d022733925af70a38b715David Lawrence<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
e85ffb301b294d70ddc1d90234788403666bb944David Lawrence<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<table width="100%" summary="Navigation header">
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<th width="60%" align="center">Manual pages</th>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<a name="man.rndc.conf"></a><div class="titlepage"></div>
5a6e6c2c9b2f6cf426aa2a682aa800765e26d540Andreas Gustafsson<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
c968a9ca37964ae0bdc5d452ad784ec93bd04c57David Lawrence<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<a name="id-1.14.28.7"></a><h2>DESCRIPTION</h2>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<p><code class="filename">rndc.conf</code> is the configuration file
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence utility. This file has a similar structure and syntax to
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley <code class="filename">named.conf</code>. Statements are enclosed
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley in braces and terminated with a semi-colon. Clauses in
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews the statements are also semi-colon terminated. The usual
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews comment styles are supported:
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews C style: /* */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews C++ style: // to end of line
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews Unix style: # to end of line
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p><code class="filename">rndc.conf</code> is much simpler than
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="filename">named.conf</code>. The file uses three
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews statements: an options statement, a server statement
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews and a key statement.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The <code class="option">options</code> statement contains five clauses.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The <code class="option">default-server</code> clause is followed by the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews name or address of a name server. This host will be used when
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews no name server is given as an argument to
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews clause is followed by the name of a key which is identified by
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews a <code class="option">key</code> statement. If no
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">keyid</code> is provided on the rndc command line,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews and no <code class="option">key</code> clause is found in a matching
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">server</code> statement, this default key will be
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews used to authenticate the server's commands and responses. The
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews <code class="option">default-port</code> clause is followed by the port
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews to connect to on the remote name server. If no
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews <code class="option">port</code> option is provided on the rndc command
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews line, and no <code class="option">port</code> clause is found in a
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews matching <code class="option">server</code> statement, this default port
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews will be used to connect.
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews The <code class="option">default-source-address</code> and
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews <code class="option">default-source-address-v6</code> clauses which
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews can be used to set the IPv4 and IPv6 source addresses
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews respectively.
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews After the <code class="option">server</code> keyword, the server
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews statement includes a string which is the hostname or address
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews for a name server. The statement has three possible clauses:
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews <code class="option">key</code>, <code class="option">port</code> and
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews <code class="option">addresses</code>. The key name must match the
e107074f370ee86275bd64ab8bcaa429fec1c7e2Mark Andrews name of a key statement in the file. The port number
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews specifies the port to connect to. If an <code class="option">addresses</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews clause is supplied these addresses will be used instead of
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews the server name. Each address can take an optional port.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence of supplied then these will be used to specify the IPv4 and IPv6
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence source addresses respectively.
4b598d8ae578861d5f3fc1333c9f84c9c9c8be7cDavid Lawrence The <code class="option">key</code> statement begins with an identifying
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews string, the name of the key. The statement has two clauses.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">algorithm</code> identifies the authentication algorithm
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (default), HMAC-SHA384 and HMAC-SHA512 are
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews supported. This is followed by a secret clause which contains
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews the base-64 encoding of the algorithm's authentication key. The
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews base-64 string is enclosed in double quotes.
f6161d8b90541b52946ae845bc8e2bec2647d6cbMark Andrews There are two common ways to generate the base-64 string for the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews be used to generate a random key, or the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="command"><strong>mmencode</strong></span> program, also known as
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <span class="command"><strong>mimencode</strong></span>, can be used to generate a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews string from known input. <span class="command"><strong>mmencode</strong></span> does
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews ship with BIND 9 but is available on many systems. See the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews EXAMPLE section for sample command lines for each.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence default-server localhost;
4b598d8ae578861d5f3fc1333c9f84c9c9c8be7cDavid Lawrence default-key samplekey;
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence server localhost {
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence key samplekey;
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence server testserver {
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence addresses { localhost port 5353; };
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence key samplekey {
1fa26403d7679235a30fbf6289f68fed5872df30Mark Andrews algorithm hmac-sha256;
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence key testkey {
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence algorithm hmac-sha256;
5a48c9f76003a649e16de34fe6206e3b67b97afbBob Halley secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence In the above example, <span class="command"><strong>rndc</strong></span> will by
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence the server at localhost (127.0.0.1) and the key called samplekey.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence Commands to the localhost server will use the samplekey key, which
4b598d8ae578861d5f3fc1333c9f84c9c9c8be7cDavid Lawrence must also be defined in the server's configuration file with the
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence same name and secret. The key statement indicates that samplekey
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence uses the HMAC-SHA256 algorithm and its secret clause contains the
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence connect to server on localhost port 5353 using the key testkey.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<p><strong class="userinput"><code>rndc-confgen</code></strong>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence A complete <code class="filename">rndc.conf</code> file, including
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence randomly generated key, will be written to the standard
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence output. Commented-out <code class="option">key</code> and
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence <code class="option">controls</code> statements for
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence <code class="filename">named.conf</code> are also printed.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<a name="id-1.14.28.9"></a><h2>NAME SERVER CONFIGURATION</h2>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence The name server must be configured to accept rndc connections and
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence to recognize the key specified in the <code class="filename">rndc.conf</code>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence file, using the controls statement in <code class="filename">named.conf</code>.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence See the sections on the <code class="option">controls</code> statement in the
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence BIND 9 Administrator Reference Manual for details.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<table width="100%" summary="Navigation footer">
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>
f4a7d04843eb62c92f2d4ff338da49ae86e3279bDavid Lawrence<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.0rc1</p>