contrib/bind-9.2.4rc7/bin/rndc/rndc.conf.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: rndc.conf.html,v 1.5.2.3 2004/06/03 05:21:16 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >rndc.conf</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 ><TT
  39 CLASS="FILENAME"
  40 >rndc.conf</TT
  41 ></A
  42 ></H1
  43 ><DIV
  44 CLASS="REFNAMEDIV"
  45 ><A
  46 NAME="AEN9"
  47 ></A
  48 ><H2
  49 >Name</H2
  50 ><TT
  51 CLASS="FILENAME"
  52 >rndc.conf</TT
  53 >&nbsp;--&nbsp;rndc configuration file</DIV
  54 ><DIV
  55 CLASS="REFSYNOPSISDIV"
  56 ><A
  57 NAME="AEN13"
  58 ></A
  59 ><H2
  60 >Synopsis</H2
  61 ><P
  62 ><B
  63 CLASS="COMMAND"
  64 >rndc.conf</B
  65 > </P
  66 ></DIV
  67 ><DIV
  68 CLASS="REFSECT1"
  69 ><A
  70 NAME="AEN16"
  71 ></A
  72 ><H2
  73 >DESCRIPTION</H2
  74 ><P
  75 >        <TT
  76 CLASS="FILENAME"
  77 >rndc.conf</TT
  78 > is the configuration file
  79         for <B
  80 CLASS="COMMAND"
  81 >rndc</B
  82 >, the BIND 9 name server control
  83         utility.  This file has a similar structure and syntax to
  84         <TT
  85 CLASS="FILENAME"
  86 >named.conf</TT
  87 >.  Statements are enclosed
  88         in braces and terminated with a semi-colon.  Clauses in
  89         the statements are also semi-colon terminated.  The usual
  90         comment styles are supported:
  91     </P
  92 ><P
  93 >        C style: /* */
  94     </P
  95 ><P
  96 >        C++ style: // to end of line
  97     </P
  98 ><P
  99 >        Unix style: # to end of line
 100     </P
 101 ><P
 102 >        <TT
 103 CLASS="FILENAME"
 104 >rndc.conf</TT
 105 > is much simpler than
 106         <TT
 107 CLASS="FILENAME"
 108 >named.conf</TT
 109 >.  The file uses three
 110         statements: an options statement, a server statement
 111         and a key statement.
 112     </P
 113 ><P
 114 >        The <TT
 115 CLASS="OPTION"
 116 >options</TT
 117 > statement contains three clauses.
 118         The <TT
 119 CLASS="OPTION"
 120 >default-server</TT
 121 > clause is followed by the
 122         name or address of a name server.  This host will be used when
 123         no name server is given as an argument to
 124         <B
 125 CLASS="COMMAND"
 126 >rndc</B
 127 >.  The <TT
 128 CLASS="OPTION"
 129 >default-key</TT
 130 >
 131         clause is followed by the name of a key which is identified by
 132         a <TT
 133 CLASS="OPTION"
 134 >key</TT
 135 > statement.  If no
 136         <TT
 137 CLASS="OPTION"
 138 >keyid</TT
 139 > is provided on the rndc command line,
 140         and no <TT
 141 CLASS="OPTION"
 142 >key</TT
 143 > clause is found in a matching
 144         <TT
 145 CLASS="OPTION"
 146 >server</TT
 147 > statement, this default key will be
 148         used to authenticate the server's commands and responses.  The
 149         <TT
 150 CLASS="OPTION"
 151 >default-port</TT
 152 > clause is followed by the port
 153         to connect to on the remote name server.  If no
 154         <TT
 155 CLASS="OPTION"
 156 >port</TT
 157 > option is provided on the rndc command
 158         line, and no <TT
 159 CLASS="OPTION"
 160 >port</TT
 161 > clause is found in a
 162         matching <TT
 163 CLASS="OPTION"
 164 >server</TT
 165 > statement, this default port
 166         will be used to connect.
 167     </P
 168 ><P
 169 >        After the <TT
 170 CLASS="OPTION"
 171 >server</TT
 172 > keyword, the server statement
 173         includes a string which is the hostname or address for a name
 174         server.  The statement has two possible clauses:
 175         <TT
 176 CLASS="OPTION"
 177 >key</TT
 178 > and <TT
 179 CLASS="OPTION"
 180 >port</TT
 181 >. The key name must
 182         match the name of a key statement in the file.  The port number
 183         specifies the port to connect to.
 184     </P
 185 ><P
 186 >        The <TT
 187 CLASS="OPTION"
 188 >key</TT
 189 > statement begins with an identifying
 190         string, the name of the key.  The statement has two clauses.
 191         <TT
 192 CLASS="OPTION"
 193 >algorithm</TT
 194 > identifies the encryption algorithm
 195         for <B
 196 CLASS="COMMAND"
 197 >rndc</B
 198 > to use; currently only HMAC-MD5 is
 199         supported.  This is followed by a secret clause which contains
 200         the base-64 encoding of the algorithm's encryption key.  The
 201         base-64 string is enclosed in double quotes.
 202     </P
 203 ><P
 204 >        There are two common ways to generate the base-64 string for the
 205         secret.  The BIND 9 program <B
 206 CLASS="COMMAND"
 207 >rndc-confgen</B
 208 > can
 209         be used to generate a random key, or the
 210         <B
 211 CLASS="COMMAND"
 212 >mmencode</B
 213 > program, also known as
 214         <B
 215 CLASS="COMMAND"
 216 >mimencode</B
 217 >, can be used to generate a base-64
 218         string from known input.  <B
 219 CLASS="COMMAND"
 220 >mmencode</B
 221 > does not
 222         ship with BIND 9 but is available on many systems.  See the
 223         EXAMPLE section for sample command lines for each.
 224     </P
 225 ></DIV
 226 ><DIV
 227 CLASS="REFSECT1"
 228 ><A
 229 NAME="AEN54"
 230 ></A
 231 ><H2
 232 >EXAMPLE</H2
 233 ><PRE
 234 CLASS="PROGRAMLISTING"
 235 >    options {
 236         default-server  localhost;
 237         default-key     samplekey;
 238       };
 239
 240       server localhost {
 241         key             samplekey;
 242       };
 243
 244       key samplekey {
 245         algorithm       hmac-md5;
 246         secret          "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
 247       };
 248     </PRE
 249 ><P
 250 >        In the above example, <B
 251 CLASS="COMMAND"
 252 >rndc</B
 253 > will by default use
 254         the server at localhost (127.0.0.1) and the key called samplekey.
 255         Commands to the localhost server will use the samplekey key, which
 256         must also be defined in the server's configuration file with the
 257         same name and secret.  The key statement indicates that samplekey
 258         uses the HMAC-MD5 algorithm and its secret clause contains the
 259         base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
 260     </P
 261 ><P
 262 >        To generate a random secret with <B
 263 CLASS="COMMAND"
 264 >rndc-confgen</B
 265 >:
 266     </P
 267 ><P
 268 >        <TT
 269 CLASS="USERINPUT"
 270 ><B
 271 >rndc-confgen</B
 272 ></TT
 273 >
 274     </P
 275 ><P
 276 >        A complete <TT
 277 CLASS="FILENAME"
 278 >rndc.conf</TT
 279 > file, including the
 280         randomly generated key, will be written to the standard
 281         output.  Commented out <TT
 282 CLASS="OPTION"
 283 >key</TT
 284 > and
 285         <TT
 286 CLASS="OPTION"
 287 >controls</TT
 288 > statements for
 289         <TT
 290 CLASS="FILENAME"
 291 >named.conf</TT
 292 > are also printed.
 293     </P
 294 ><P
 295 >        To generate a base-64 secret with <B
 296 CLASS="COMMAND"
 297 >mmencode</B
 298 >:
 299     </P
 300 ><P
 301 >        <TT
 302 CLASS="USERINPUT"
 303 ><B
 304 >echo "known plaintext for a secret" | mmencode</B
 305 ></TT
 306 >
 307     </P
 308 ></DIV
 309 ><DIV
 310 CLASS="REFSECT1"
 311 ><A
 312 NAME="AEN72"
 313 ></A
 314 ><H2
 315 >NAME SERVER CONFIGURATION</H2
 316 ><P
 317 >        The name server must be configured to accept rndc connections and
 318         to recognize the key specified in the <TT
 319 CLASS="FILENAME"
 320 >rndc.conf</TT
 321 >
 322         file, using the controls statement in <TT
 323 CLASS="FILENAME"
 324 >named.conf</TT
 325 >.
 326         See the sections on the <TT
 327 CLASS="OPTION"
 328 >controls</TT
 329 > statement in the
 330         BIND 9 Administrator Reference Manual for details.
 331     </P
 332 ></DIV
 333 ><DIV
 334 CLASS="REFSECT1"
 335 ><A
 336 NAME="AEN78"
 337 ></A
 338 ><H2
 339 >SEE ALSO</H2
 340 ><P
 341 >      <SPAN
 342 CLASS="CITEREFENTRY"
 343 ><SPAN
 344 CLASS="REFENTRYTITLE"
 345 >rndc</SPAN
 346 >(8)</SPAN
 347 >,
 348       <SPAN
 349 CLASS="CITEREFENTRY"
 350 ><SPAN
 351 CLASS="REFENTRYTITLE"
 352 >rndc-confgen</SPAN
 353 >(8)</SPAN
 354 >,
 355       <SPAN
 356 CLASS="CITEREFENTRY"
 357 ><SPAN
 358 CLASS="REFENTRYTITLE"
 359 >mmencode</SPAN
 360 >(1)</SPAN
 361 >,
 362       <I
 363 CLASS="CITETITLE"
 364 >BIND 9 Administrator Reference Manual</I
 365 >.
 366     </P
 367 ></DIV
 368 ><DIV
 369 CLASS="REFSECT1"
 370 ><A
 371 NAME="AEN91"
 372 ></A
 373 ><H2
 374 >AUTHOR</H2
 375 ><P
 376 >        Internet Systems Consortium
 377     </P
 378 ></DIV
 379 ></BODY
 380 ></HTML
 381 >