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