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