rndc.conf.html revision 36e0109263bd544578c245fe8db1e2718e8a8551
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2001 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - purpose with or without fee is hereby granted, provided that the above
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - copyright notice and this permission notice appear in all copies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: rndc.conf.html,v 1.10 2004/06/18 06:00:41 marka Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNAME="GENERATOR"
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="REFENTRY"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinBGCOLOR="#FFFFFF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTEXT="#000000"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserLINK="#0000FF"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserVLINK="#840084"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserALINK="#0000FF"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFNAMEDIV"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> -- rndc configuration file</DIV
c2258eedf2d9d0207b45b90014f8fde5413b41a3Tinderbox UserCLASS="REFSYNOPSISDIV"
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox UserCLASS="COMMAND"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFSECT1"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>DESCRIPTION</H2
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> is the configuration file
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserCLASS="COMMAND"
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User>, the BIND 9 name server control
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User utility. This file has a similar structure and syntax to
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserCLASS="FILENAME"
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User>. Statements are enclosed
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User in braces and terminated with a semi-colon. Clauses in
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User the statements are also semi-colon terminated. The usual
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User comment styles are supported:
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User> C style: /* */
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User> C++ style: // to end of line
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User> Unix style: # to end of line
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserCLASS="FILENAME"
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User> is much simpler than
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserCLASS="FILENAME"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>. The file uses three
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox User statements: an options statement, a server statement
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User and a key statement.
576bce9d7331498ca5453f8743f94ed8e2e59d9fTinderbox UserCLASS="OPTION"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> statement contains three clauses.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>default-server</TT
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> clause is followed by the
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User name or address of a name server. This host will be used when
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User no name server is given as an argument to
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="COMMAND"
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="OPTION"
1ffe3f29e3cd0d8355500e9fd34de918ad9b4a01Tinderbox User>default-key</TT
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User clause is followed by the name of a key which is identified by
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="OPTION"
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User> statement. If no
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="OPTION"
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User> is provided on the rndc command line,
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="OPTION"
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User> clause is found in a matching
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserCLASS="OPTION"
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User> statement, this default key will be
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User used to authenticate the server's commands and responses. The
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserCLASS="OPTION"
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User>default-port</TT
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User> clause is followed by the port
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User to connect to on the remote name server. If no
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox UserCLASS="OPTION"
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User> option is provided on the rndc command
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox User line, and no <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> clause is found in a
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt matching <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> statement, this default port
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User will be used to connect.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> After the <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> keyword, the server
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt statement includes a string which is the hostname or address
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User for a name server. The statement has three possible clauses:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>addresses</TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>. The key name must match the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt name of a key statement in the file. The port number
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt specifies the port to connect to. If an <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User>addresses</TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt clause is supplied these addresses will be used instead of
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User the server name. Each address can take a optional port.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> statement begins with an identifying
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt string, the name of the key. The statement has two clauses.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="OPTION"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User>algorithm</TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> identifies the encryption algorithm
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="COMMAND"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> to use; currently only HMAC-MD5 is
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt supported. This is followed by a secret clause which contains
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User the base-64 encoding of the algorithm's encryption key. The
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt base-64 string is enclosed in double quotes.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> There are two common ways to generate the base-64 string for the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt secret. The BIND 9 program <B
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="COMMAND"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>rndc-confgen</B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt be used to generate a random key, or the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="COMMAND"
9d557856c2a19ec95ee73245f60a92f8675cf5baTinderbox User> program, also known as
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="COMMAND"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>mimencode</B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>, can be used to generate a base-64
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User string from known input. <B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="COMMAND"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt ship with BIND 9 but is available on many systems. See the
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox User EXAMPLE section for sample command lines for each.
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox UserCLASS="REFSECT1"
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox UserCLASS="PROGRAMLISTING"
1700442a7751c2bbdafe2d039cebbd8316496957Tinderbox User default-server localhost;
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox User default-key samplekey;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User server localhost {
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt key samplekey;
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User server testserver {
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt key testkey;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt addresses { localhost port 5353; };
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt key samplekey {
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt algorithm hmac-md5;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User key testkey {
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User algorithm hmac-md5;
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User> In the above example, <B
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserCLASS="COMMAND"
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User> will by default use
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User the server at localhost (127.0.0.1) and the key called samplekey.
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User Commands to the localhost server will use the samplekey key, which
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User must also be defined in the server's configuration file with the
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User same name and secret. The key statement indicates that samplekey
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User uses the HMAC-MD5 algorithm and its secret clause contains the
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserCLASS="COMMAND"
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User>rndc -s testserver</B
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User> is used then <B
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserCLASS="COMMAND"
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User connect to server on localhost port 5353 using the key testkey.
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User> To generate a random secret with <B
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserCLASS="COMMAND"
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User>rndc-confgen</B
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox UserCLASS="USERINPUT"
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User>rndc-confgen</B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> A complete <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> file, including the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt randomly generated key, will be written to the standard
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User output. Commented out <TT
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>controls</TT
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User> statements for
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> are also printed.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> To generate a base-64 secret with <B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="COMMAND"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="USERINPUT"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User>echo "known plaintext for a secret" | mmencode</B
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFSECT1"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>NAME SERVER CONFIGURATION</H2
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt> The name server must be configured to accept rndc connections and
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User to recognize the key specified in the <TT
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="FILENAME"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt file, using the controls statement in <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FILENAME"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt See the sections on the <TT
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="OPTION"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> statement in the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt BIND 9 Administrator Reference Manual for details.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFSECT1"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>SEE ALSO</H2
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CITEREFENTRY"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFENTRYTITLE"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="CITEREFENTRY"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFENTRYTITLE"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>rndc-confgen</SPAN
0226754d9e537fd56b690d5890cfe215a6c59f89Tinderbox UserCLASS="CITEREFENTRY"
0226754d9e537fd56b690d5890cfe215a6c59f89Tinderbox UserCLASS="REFENTRYTITLE"
eb2a5f51bd5c100799d93d51c9e22666cbd64d90Tinderbox User>mmencode</SPAN
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="CITETITLE"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>BIND 9 Administrator Reference Manual</I
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="REFSECT1"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User> Internet Systems Consortium