contrib/bind9/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.1.4.3 2004/08/22 23:39:00 marka Exp $ -->
  19
  20 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  21 <HTML
  22 ><HEAD
  23 ><TITLE
  24 >rndc.conf</TITLE
  25 ><META
  26 NAME="GENERATOR"
  27 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></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 ></A
  39 ><TT
  40 CLASS="FILENAME"
  41 >rndc.conf</TT
  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 <VAR
 115 CLASS="OPTION"
 116 >options</VAR
 117 > statement contains three clauses.
 118         The <VAR
 119 CLASS="OPTION"
 120 >default-server</VAR
 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 <VAR
 128 CLASS="OPTION"
 129 >default-key</VAR
 130 >
 131         clause is followed by the name of a key which is identified by
 132         a <VAR
 133 CLASS="OPTION"
 134 >key</VAR
 135 > statement.  If no
 136         <VAR
 137 CLASS="OPTION"
 138 >keyid</VAR
 139 > is provided on the rndc command line,
 140         and no <VAR
 141 CLASS="OPTION"
 142 >key</VAR
 143 > clause is found in a matching
 144         <VAR
 145 CLASS="OPTION"
 146 >server</VAR
 147 > statement, this default key will be
 148         used to authenticate the server's commands and responses.  The
 149         <VAR
 150 CLASS="OPTION"
 151 >default-port</VAR
 152 > clause is followed by the port
 153         to connect to on the remote name server.  If no
 154         <VAR
 155 CLASS="OPTION"
 156 >port</VAR
 157 > option is provided on the rndc command
 158         line, and no <VAR
 159 CLASS="OPTION"
 160 >port</VAR
 161 > clause is found in a
 162         matching <VAR
 163 CLASS="OPTION"
 164 >server</VAR
 165 > statement, this default port
 166         will be used to connect.
 167     </P
 168 ><P
 169 >        After the <VAR
 170 CLASS="OPTION"
 171 >server</VAR
 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         <VAR
 176 CLASS="OPTION"
 177 >key</VAR
 178 > and <VAR
 179 CLASS="OPTION"
 180 >port</VAR
 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 <VAR
 187 CLASS="OPTION"
 188 >key</VAR
 189 > statement begins with an identifying
 190         string, the name of the key.  The statement has two clauses.
 191         <VAR
 192 CLASS="OPTION"
 193 >algorithm</VAR
 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 >        <KBD
 269 CLASS="USERINPUT"
 270 >rndc-confgen</KBD
 271 >
 272     </P
 273 ><P
 274 >        A complete <TT
 275 CLASS="FILENAME"
 276 >rndc.conf</TT
 277 > file, including the
 278         randomly generated key, will be written to the standard
 279         output.  Commented out <VAR
 280 CLASS="OPTION"
 281 >key</VAR
 282 > and
 283         <VAR
 284 CLASS="OPTION"
 285 >controls</VAR
 286 > statements for
 287         <TT
 288 CLASS="FILENAME"
 289 >named.conf</TT
 290 > are also printed.
 291     </P
 292 ><P
 293 >        To generate a base-64 secret with <B
 294 CLASS="COMMAND"
 295 >mmencode</B
 296 >:
 297     </P
 298 ><P
 299 >        <KBD
 300 CLASS="USERINPUT"
 301 >echo "known plaintext for a secret" | mmencode</KBD
 302 >
 303     </P
 304 ></DIV
 305 ><DIV
 306 CLASS="REFSECT1"
 307 ><A
 308 NAME="AEN72"
 309 ></A
 310 ><H2
 311 >NAME SERVER CONFIGURATION</H2
 312 ><P
 313 >        The name server must be configured to accept rndc connections and
 314         to recognize the key specified in the <TT
 315 CLASS="FILENAME"
 316 >rndc.conf</TT
 317 >
 318         file, using the controls statement in <TT
 319 CLASS="FILENAME"
 320 >named.conf</TT
 321 >.
 322         See the sections on the <VAR
 323 CLASS="OPTION"
 324 >controls</VAR
 325 > statement in the
 326         BIND 9 Administrator Reference Manual for details.
 327     </P
 328 ></DIV
 329 ><DIV
 330 CLASS="REFSECT1"
 331 ><A
 332 NAME="AEN78"
 333 ></A
 334 ><H2
 335 >SEE ALSO</H2
 336 ><P
 337 >      <SPAN
 338 CLASS="CITEREFENTRY"
 339 ><SPAN
 340 CLASS="REFENTRYTITLE"
 341 >rndc</SPAN
 342 >(8)</SPAN
 343 >,
 344       <SPAN
 345 CLASS="CITEREFENTRY"
 346 ><SPAN
 347 CLASS="REFENTRYTITLE"
 348 >rndc-confgen</SPAN
 349 >(8)</SPAN
 350 >,
 351       <SPAN
 352 CLASS="CITEREFENTRY"
 353 ><SPAN
 354 CLASS="REFENTRYTITLE"
 355 >mmencode</SPAN
 356 >(1)</SPAN
 357 >,
 358       <I
 359 CLASS="CITETITLE"
 360 >BIND 9 Administrator Reference Manual</I
 361 >.
 362     </P
 363 ></DIV
 364 ><DIV
 365 CLASS="REFSECT1"
 366 ><A
 367 NAME="AEN91"
 368 ></A
 369 ><H2
 370 >AUTHOR</H2
 371 ><P
 372 >        Internet Systems Consortium
 373     </P
 374 ></DIV
 375 ></BODY
 376 ></HTML
 377 >