rndc.conf.html revision fd2597f75693a2279fdf588bd40dfe2407c42028
1633838b8255282d10af15c5c84cee5a51466712Bob Halley<!--
5dee04703805e9453ff4d8d77884391e3a185977Bob Halley - Copyright (C) 2004, 2005, 2007, 2013-2015 Internet Systems Consortium, Inc. ("ISC")
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - Copyright (C) 2000, 2001 Internet Software Consortium.
1633838b8255282d10af15c5c84cee5a51466712Bob Halley -
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - Permission to use, copy, modify, and/or distribute this software for any
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - purpose with or without fee is hereby granted, provided that the above
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - copyright notice and this permission notice appear in all copies.
1633838b8255282d10af15c5c84cee5a51466712Bob Halley -
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
1633838b8255282d10af15c5c84cee5a51466712Bob Halley - PERFORMANCE OF THIS SOFTWARE.
1633838b8255282d10af15c5c84cee5a51466712Bob Halley-->
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<html>
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<head>
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<title>rndc.conf</title>
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
e4e071ae12aee942fefc2c0a3280e402938669deBob Halley</head>
e4e071ae12aee942fefc2c0a3280e402938669deBob Halley<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley<a name="man.rndc.conf"></a><div class="titlepage"></div>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<div class="refnamediv">
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<h2>Name</h2>
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley<p><code class="filename">rndc.conf</code> &#8212; rndc configuration file</p>
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley</div>
e4e071ae12aee942fefc2c0a3280e402938669deBob Halley<div class="refsynopsisdiv">
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<h2>Synopsis</h2>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley</div>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<div class="refsection">
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<a name="id-1.7"></a><h2>DESCRIPTION</h2>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<p><code class="filename">rndc.conf</code> is the configuration file
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington utility. This file has a similar structure and syntax to
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="filename">named.conf</code>. Statements are enclosed
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington in braces and terminated with a semi-colon. Clauses in
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington the statements are also semi-colon terminated. The usual
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington comment styles are supported:
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington </p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington C style: /* */
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley </p>
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley<p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley C++ style: // to end of line
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley </p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington Unix style: # to end of line
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington </p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<p><code class="filename">rndc.conf</code> is much simpler than
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="filename">named.conf</code>. The file uses three
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington statements: an options statement, a server statement
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington and a key statement.
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington </p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington The <code class="option">options</code> statement contains five clauses.
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington The <code class="option">default-server</code> clause is followed by the
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington name or address of a name server. This host will be used when
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington no name server is given as an argument to
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington clause is followed by the name of a key which is identified by
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley a <code class="option">key</code> statement. If no
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="option">keyid</code> is provided on the rndc command line,
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington and no <code class="option">key</code> clause is found in a matching
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="option">server</code> statement, this default key will be
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington used to authenticate the server's commands and responses. The
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="option">default-port</code> clause is followed by the port
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington to connect to on the remote name server. If no
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="option">port</code> option is provided on the rndc command
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington line, and no <code class="option">port</code> clause is found in a
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington matching <code class="option">server</code> statement, this default port
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington will be used to connect.
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington The <code class="option">default-source-address</code> and
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington <code class="option">default-source-address-v6</code> clauses which
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington can be used to set the IPv4 and IPv6 source addresses
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington respectively.
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington </p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington<p>
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington After the <code class="option">server</code> keyword, the server
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington statement includes a string which is the hostname or address
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley for a name server. The statement has three possible clauses:
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley <code class="option">key</code>, <code class="option">port</code> and
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley <code class="option">addresses</code>. The key name must match the
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley name of a key statement in the file. The port number
308c7ad5f68301d19f023af616f62f3e7cbce632Andreas Gustafsson specifies the port to connect to. If an <code class="option">addresses</code>
04b8111f2137a9cf9b0b71228f76b3e40ffa1173Brian Wellington clause is supplied these addresses will be used instead of
04b8111f2137a9cf9b0b71228f76b3e40ffa1173Brian Wellington the server name. Each address can take an optional port.
ccad3c9ecbe8a1060ff7b407a318ccd592de536eBrian Wellington If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
ccad3c9ecbe8a1060ff7b407a318ccd592de536eBrian Wellington of supplied then these will be used to specify the IPv4 and IPv6
ccad3c9ecbe8a1060ff7b407a318ccd592de536eBrian Wellington source addresses respectively.
ccad3c9ecbe8a1060ff7b407a318ccd592de536eBrian Wellington </p>
ccad3c9ecbe8a1060ff7b407a318ccd592de536eBrian Wellington<p>
8224be5129daebea8f0f5e8be5f925679ec893f1Brian Wellington The <code class="option">key</code> statement begins with an identifying
8224be5129daebea8f0f5e8be5f925679ec893f1Brian Wellington string, the name of the key. The statement has two clauses.
a413f94248ceed48a6b7aaa2fa1d2401fb8b9f30Brian Wellington <code class="option">algorithm</code> identifies the authentication algorithm
d14b749789121d9d502fa1348e9e73270e9b039fBob Halley for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
63d1ef9e771b748ca9bf241dfc1f07d3730203faBob Halley (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
659175b7d430afe13b439e499442a964e2c9110fMark Andrews (default), HMAC-SHA384 and HMAC-SHA512 are
cd02757774252fe5b92dbd59a24b34721fb49ff4Bob Halley supported. This is followed by a secret clause which contains
cd02757774252fe5b92dbd59a24b34721fb49ff4Bob Halley the base-64 encoding of the algorithm's authentication key. The
7b4dcbb89b71b17f5c16ca19a0e705e09509f063Bob Halley base-64 string is enclosed in double quotes.
73af6575e00f8cf4942abce177f435797b9cfe41Brian Wellington </p>
322b0fb39dd1538c9f5021cd2f54d4c12684ecdbBrian Wellington<p>
3864eb0e9a73148ac744893b5367169761184db5Mark Andrews There are two common ways to generate the base-64 string for the
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
3864eb0e9a73148ac744893b5367169761184db5Mark Andrews can
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley be used to generate a random key, or the
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley <span class="command"><strong>mmencode</strong></span> program, also known as
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley <span class="command"><strong>mimencode</strong></span>, can be used to generate a
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley base-64
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley string from known input. <span class="command"><strong>mmencode</strong></span> does
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley not
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley ship with BIND 9 but is available on many systems. See the
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley EXAMPLE section for sample command lines for each.
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley </p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley</div>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<div class="refsection">
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<a name="id-1.8"></a><h2>EXAMPLE</h2>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<pre class="programlisting">
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley options {
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley default-server localhost;
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley default-key samplekey;
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley };
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley</pre>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley </p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<pre class="programlisting">
125d72976ab6b8fa6629a5ace276a86e9fef91acBrian Wellington server localhost {
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley key samplekey;
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley };
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley</pre>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley </p>
25e43e68b7431d5e4ff8b5427108cd7f5f9bcf3eBob Halley<pre class="programlisting">
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley server testserver {
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley key testkey;
904a5734375869ffb504ed8cde6b68cafadb6d64Bob Halley addresses { localhost port 5353; };
c50fd34a4e0e6978f8ca5f6f3ad8545549c3cfeeBob Halley };
</pre>
<p>
</p>
<pre class="programlisting">
key samplekey {
algorithm hmac-sha256;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
};
</pre>
<p>
</p>
<pre class="programlisting">
key testkey {
algorithm hmac-sha256;
secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
};
</pre>
<p>
</p>
<p>
In the above example, <span class="command"><strong>rndc</strong></span> will by
default use
the server at localhost (127.0.0.1) and the key called samplekey.
Commands to the localhost server will use the samplekey key, which
must also be defined in the server's configuration file with the
same name and secret. The key statement indicates that samplekey
uses the HMAC-SHA256 algorithm and its secret clause contains the
base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
</p>
<p>
If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
connect to server on localhost port 5353 using the key testkey.
</p>
<p>
To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
</p>
<p><strong class="userinput"><code>rndc-confgen</code></strong>
</p>
<p>
A complete <code class="filename">rndc.conf</code> file, including
the
randomly generated key, will be written to the standard
output. Commented-out <code class="option">key</code> and
<code class="option">controls</code> statements for
<code class="filename">named.conf</code> are also printed.
</p>
<p>
To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
</p>
<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
</p>
</div>
<div class="refsection">
<a name="id-1.9"></a><h2>NAME SERVER CONFIGURATION</h2>
<p>
The name server must be configured to accept rndc connections and
to recognize the key specified in the <code class="filename">rndc.conf</code>
file, using the controls statement in <code class="filename">named.conf</code>.
See the sections on the <code class="option">controls</code> statement in the
BIND 9 Administrator Reference Manual for details.
</p>
</div>
<div class="refsection">
<a name="id-1.10"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
<em class="citetitle">BIND 9 Administrator Reference Manual</em>.
</p>
</div>
</div></body>
</html>