rndc.conf.html revision 33d0a7767d53cb366039fd0ac4f63cf8a9c351b0
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004, 2005, 2007, 2013-2016 Internet Systems Consortium, Inc. ("ISC")
7a2a1b8b14fc804ac80612d7b98064095e445be5Automatic Updater - Copyright (C) 2000, 2001 Internet Software Consortium.
1167fc7904c5f0a472f8df207ac46dd52c7f1ec8Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
0c39b3ed9409ecb277d5e32fa763a4e4d6598df8Automatic Updater - purpose with or without fee is hereby granted, provided that the above
46da3117812814a29432a8d9a9ccf8acdbfdadceAutomatic Updater - copyright notice and this permission notice appear in all copies.
fe84edc17e0d582cf7b4270f8df9d4742a107b1cAutomatic Updater - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
79b273c187a4aa1016a62181983dfdd0521681aeMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
6c6a121295b30772cbf3dd75a51fb9d883051a0eAutomatic Updater - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater - PERFORMANCE OF THIS SOFTWARE.
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
bbde8dc56605130058a1540609264fa109da3b63Automatic Updater<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
bbde8dc56605130058a1540609264fa109da3b63Automatic Updater<a name="man.rndc.conf"></a><div class="titlepage"></div>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<p><code class="filename">rndc.conf</code> is the configuration file
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater utility. This file has a similar structure and syntax to
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="filename">named.conf</code>. Statements are enclosed
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt in braces and terminated with a semi-colon. Clauses in
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater the statements are also semi-colon terminated. The usual
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater comment styles are supported:
e130ab53e992670e2a2ecf043976ac09f21358d1Automatic Updater C style: /* */
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater C++ style: // to end of line
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater Unix style: # to end of line
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater<p><code class="filename">rndc.conf</code> is much simpler than
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <code class="filename">named.conf</code>. The file uses three
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater statements: an options statement, a server statement
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater and a key statement.
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews The <code class="option">options</code> statement contains five clauses.
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews The <code class="option">default-server</code> clause is followed by the
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User name or address of a name server. This host will be used when
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater 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>
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater clause is followed by the name of a key which is identified by
8e9f3b69914ee02a80b87c97b1f8093edb3e9ae0Automatic Updater a <code class="option">key</code> statement. If no
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">keyid</code> is provided on the rndc command line,
930f6069e5aa157cf6987cdafd412f5757a5a558Automatic Updater 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
930f6069e5aa157cf6987cdafd412f5757a5a558Automatic Updater used to authenticate the server's commands and responses. The
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater <code class="option">default-port</code> clause is followed by the port
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews to connect to on the remote name server. If no
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater <code class="option">port</code> option is provided on the rndc command
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews line, and no <code class="option">port</code> clause is found in a
930f6069e5aa157cf6987cdafd412f5757a5a558Automatic Updater matching <code class="option">server</code> statement, this default port
693c4232dfdffaff672197d4b9fea944c64cf80aAutomatic Updater will be used to connect.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The <code class="option">default-source-address</code> and
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <code class="option">default-source-address-v6</code> clauses which
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson can be used to set the IPv4 and IPv6 source addresses
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater After the <code class="option">server</code> keyword, the server
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson statement includes a string which is the hostname or address
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater for a name server. The statement has three possible clauses:
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater <code class="option">key</code>, <code class="option">port</code> and
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <code class="option">addresses</code>. The key name must match the
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater name of a key statement in the file. The port number
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User specifies the port to connect to. If an <code class="option">addresses</code>
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater clause is supplied these addresses will be used instead of
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews the server name. Each address can take an optional port.
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User of supplied then these will be used to specify the IPv4 and IPv6
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews source addresses respectively.
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User The <code class="option">key</code> statement begins with an identifying
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont string, the name of the key. The statement has two clauses.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <code class="option">algorithm</code> identifies the authentication algorithm
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews (default), HMAC-SHA384 and HMAC-SHA512 are
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews supported. This is followed by a secret clause which contains
24bf1e02f03577db0feb50b80238c4150c96d05dAutomatic Updater the base-64 encoding of the algorithm's authentication key. The
24bf1e02f03577db0feb50b80238c4150c96d05dAutomatic Updater base-64 string is enclosed in double quotes.
a308b69ac66fadf66863484f301314d6e6a3f1d2Automatic Updater There are two common ways to generate the base-64 string for the
a308b69ac66fadf66863484f301314d6e6a3f1d2Automatic Updater secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews be used to generate a random key, or the
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater <span class="command"><strong>mmencode</strong></span> program, also known as
82447d835d3ff5c658749b4e9b4f66166407b3eaAutomatic Updater <span class="command"><strong>mimencode</strong></span>, can be used to generate a
24bf1e02f03577db0feb50b80238c4150c96d05dAutomatic Updater string from known input. <span class="command"><strong>mmencode</strong></span> does
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater ship with BIND 9 but is available on many systems. See the
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater EXAMPLE section for sample command lines for each.
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater default-server localhost;
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson default-key samplekey;
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater server localhost {
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater key samplekey;
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User server testserver {
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User addresses { localhost port 5353; };
c6a0f4ae1d7183a16ffb196b86b647f870694796Automatic Updater key samplekey {
8f2c45a35dd8c40bcc9caba8f7d40ce64fc27bcdAutomatic Updater algorithm hmac-sha256;
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
9c446b72069d0ab9f710502f4d7048e50875fccbAutomatic Updater algorithm hmac-sha256;
e85565067cf73f8cc21ee29b11761659f1d47ee9Automatic Updater secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater In the above example, <span class="command"><strong>rndc</strong></span> will by
7f79131f9a8e804b93c57f3c679065cce878b726Automatic Updater the server at localhost (127.0.0.1) and the key called samplekey.
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater Commands to the localhost server will use the samplekey key, which
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater must also be defined in the server's configuration file with the
3f616e6f846be57b1717c6beaba0f74de9d5a7c6Automatic Updater same name and secret. The key statement indicates that samplekey
8f2c45a35dd8c40bcc9caba8f7d40ce64fc27bcdAutomatic Updater 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.
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
7f94d9a8162c9a96b56e66176702b66e79d8e1a2Automatic Updater connect to server on localhost port 5353 using the key testkey.
5ecad47f69b3fd945472ab2900a9ff826a7ce2f6Automatic Updater To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater<p><strong class="userinput"><code>rndc-confgen</code></strong>
7262eb86f2b465822206122921e2f357218f0cfdAutomatic Updater A complete <code class="filename">rndc.conf</code> file, including
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater randomly generated key, will be written to the standard
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater output. Commented-out <code class="option">key</code> and
bbb069be941f649228760edcc241122933c066d2Automatic Updater <code class="option">controls</code> statements for
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater <code class="filename">named.conf</code> are also printed.
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic Updater To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a name="id-1.9"></a><h2>NAME SERVER CONFIGURATION</h2>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The name server must be configured to accept rndc connections and
cafd3a2b9974fe0a4ab95e0289746062bd958d68Automatic Updater to recognize the key specified in the <code class="filename">rndc.conf</code>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews file, using the controls statement in <code class="filename">named.conf</code>.
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater See the sections on the <code class="option">controls</code> statement in the
7a2a1b8b14fc804ac80612d7b98064095e445be5Automatic Updater BIND 9 Administrator Reference Manual for details.
3e5340279d8875d136a4dd815cccad0044aa2644Automatic Updater<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
8711e5c73ca872d59810760af0332194cbdd619bAutomatic Updater <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
fe84edc17e0d582cf7b4270f8df9d4742a107b1cAutomatic Updater <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updater <em class="citetitle">BIND 9 Administrator Reference Manual</em>.