rndc.conf.html revision b2f07642fd712c8fda81a116bcdde229ab291f33
178f6ad061e54bc5babfca3577f72058fa0797c1Bob Halley - Copyright (C) 2004, 2005, 2007, 2013 Internet Systems Consortium, Inc. ("ISC")
c8175ece69d986ccd0671bc4d2571b247dfae177Automatic Updater - Copyright (C) 2000, 2001 Internet Software Consortium.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - Permission to use, copy, modify, and/or distribute this software for any
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - purpose with or without fee is hereby granted, provided that the above
178f6ad061e54bc5babfca3577f72058fa0797c1Bob Halley - copyright notice and this permission notice appear in all copies.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
b897c52f865b2fc4e220e2110b874e59c716456bBob Halley<!-- $Id$ -->
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<a name="man.rndc.conf"></a><div class="titlepage"></div>
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence<p><code class="filename">rndc.conf</code> is the configuration file
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley utility. This file has a similar structure and syntax to
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley <code class="filename">named.conf</code>. Statements are enclosed
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence in braces and terminated with a semi-colon. Clauses in
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence the statements are also semi-colon terminated. The usual
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence comment styles are supported:
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence C style: /* */
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence C++ style: // to end of line
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence Unix style: # to end of line
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence<p><code class="filename">rndc.conf</code> is much simpler than
dabea86dac4c01f852b7aea728f73b4f55a89d44Mark Andrews <code class="filename">named.conf</code>. The file uses three
dabea86dac4c01f852b7aea728f73b4f55a89d44Mark Andrews statements: an options statement, a server statement
dabea86dac4c01f852b7aea728f73b4f55a89d44Mark Andrews and a key statement.
2d46d268ccff30bb50e661b47c6496d23d9156c7Mark Andrews The <code class="option">options</code> statement contains five clauses.
2d46d268ccff30bb50e661b47c6496d23d9156c7Mark Andrews The <code class="option">default-server</code> clause is followed by the
dabea86dac4c01f852b7aea728f73b4f55a89d44Mark Andrews name or address of a name server. This host will be used when
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley no name server is given as an argument to
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence clause is followed by the name of a key which is identified by
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence a <code class="option">key</code> statement. If no
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence <code class="option">keyid</code> is provided on the rndc command line,
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence and no <code class="option">key</code> clause is found in a matching
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence <code class="option">server</code> statement, this default key will be
596912ee9ca8eb14d30707ec286ab5d28bd39b3eMark Andrews used to authenticate the server's commands and responses. The
8319af16557b81eba3277ee67215285f0823b587Mark Andrews <code class="option">default-port</code> clause is followed by the port
8319af16557b81eba3277ee67215285f0823b587Mark Andrews to connect to on the remote name server. If no
aee5e9cbacd8f88325840b8a498876f4319b0890Mark Andrews <code class="option">port</code> option is provided on the rndc command
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence line, and no <code class="option">port</code> clause is found in a
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence matching <code class="option">server</code> statement, this default port
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence will be used to connect.
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence The <code class="option">default-source-address</code> and
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence <code class="option">default-source-address-v6</code> clauses which
c32b87bc54abacf95fb3b063d72b7d1855c1643bMichael Graff can be used to set the IPv4 and IPv6 source addresses
7f9f8c13c5e5e26e0ba2b82c0900d11ecf6269ceMark Andrews respectively.
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence After the <code class="option">server</code> keyword, the server
12e63bfe1d111ccb57f482b28d56c785cccc7cf7David Lawrence statement includes a string which is the hostname or address
460b427411b72da26b1836b9424e2e70d65d9394David Lawrence for a name server. The statement has three possible clauses:
b616f6ed69209ab4c87f610b472aeb20760652f2Mark Andrews <code class="option">key</code>, <code class="option">port</code> and
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley <code class="option">addresses</code>. The key name must match the
2320f230995995595438a9d9301d84931fd266ceMark Andrews name of a key statement in the file. The port number
c427260a8678f2e99a2337fb95ec98d9c9ee8c05Mark Andrews specifies the port to connect to. If an <code class="option">addresses</code>
620a452ebe92fff63e85c5930a6e6dc8d9455918Mark Andrews clause is supplied these addresses will be used instead of
620a452ebe92fff63e85c5930a6e6dc8d9455918Mark Andrews the server name. Each address can take an optional port.
6dcb47e37f9f0cdb94bdabc3fa157ff07983c590Mark Andrews If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
6dcb47e37f9f0cdb94bdabc3fa157ff07983c590Mark Andrews of supplied then these will be used to specify the IPv4 and IPv6
43b3337ba58d70ca34f4d91e8c6c5e13a54af690Mark Andrews source addresses respectively.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley The <code class="option">key</code> statement begins with an identifying
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley string, the name of the key. The statement has two clauses.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley <code class="option">algorithm</code> identifies the authentication algorithm
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley (default), HMAC-SHA384 and HMAC-SHA512 are
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley supported. This is followed by a secret clause which contains
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the base-64 encoding of the algorithm's authentication key. The
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley base-64 string is enclosed in double quotes.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley There are two common ways to generate the base-64 string for the
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley be used to generate a random key, or the
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley <span><strong class="command">mmencode</strong></span> program, also known as
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley <span><strong class="command">mimencode</strong></span>, can be used to generate a
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley string from known input. <span><strong class="command">mmencode</strong></span> does
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley ship with BIND 9 but is available on many systems. See the
0014d6342b0d50ae37126ac16d5bf821d02ffff7David Lawrence EXAMPLE section for sample command lines for each.
a9558a6c63d9c6dbb2f3800b39ccb008652fcde3Mark Andrews default-server localhost;
a9558a6c63d9c6dbb2f3800b39ccb008652fcde3Mark Andrews default-key samplekey;
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley server localhost {
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley key samplekey;
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley server testserver {
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley key testkey;
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley addresses { localhost port 5353; };
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley key samplekey {
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley algorithm hmac-sha256;
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley key testkey {
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley algorithm hmac-sha256;
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley In the above example, <span><strong class="command">rndc</strong></span> will by
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley the server at localhost (127.0.0.1) and the key called samplekey.
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley Commands to the localhost server will use the samplekey key, which
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley must also be defined in the server's configuration file with the
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley same name and secret. The key statement indicates that samplekey
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley uses the HMAC-SHA256 algorithm and its secret clause contains the
0b72c791466d0807bcf22522b5ddb7da902c2720Bob Halley base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.