external/bsd/bind/dist/doc/arm/Bv9ARM.ch03.html

   1 <!--
   2  - Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000-2003 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or 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 <!-- Id: Bv9ARM.ch03.html,v 1.77 2009/10/12 23:15:32 tbox Exp -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>Chapter 3. Name Server Configuration</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 <link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
  24 <link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
  25 <link rel="prev" href="Bv9ARM.ch02.html" title="Chapter 2. BIND Resource Requirements">
  26 <link rel="next" href="Bv9ARM.ch04.html" title="Chapter 4. Advanced DNS Features">
  27 </head>
  28 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  29 <div class="navheader">
  30 <table width="100%" summary="Navigation header">
  31 <tr><th colspan="3" align="center">Chapter 3. Name Server Configuration</th></tr>
  32 <tr>
  33 <td width="20%" align="left">
  34 <a accesskey="p" href="Bv9ARM.ch02.html">Prev</a> </td>
  35 <th width="60%" align="center"> </th>
  36 <td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch04.html">Next</a>
  37 </td>
  38 </tr>
  39 </table>
  40 <hr>
  41 </div>
  42 <div class="chapter" lang="en">
  43 <div class="titlepage"><div><div><h2 class="title">
  44 <a name="Bv9ARM.ch03"></a>Chapter 3. Name Server Configuration</h2></div></div></div>
  45 <div class="toc">
  46 <p><b>Table of Contents</b></p>
  47 <dl>
  48 <dt><span class="sect1"><a href="Bv9ARM.ch03.html#sample_configuration">Sample Configurations</a></span></dt>
  49 <dd><dl>
  50 <dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2567897">A Caching-only Name Server</a></span></dt>
  51 <dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2567913">An Authoritative-only Name Server</a></span></dt>
  52 </dl></dd>
  53 <dt><span class="sect1"><a href="Bv9ARM.ch03.html#id2568004">Load Balancing</a></span></dt>
  54 <dt><span class="sect1"><a href="Bv9ARM.ch03.html#id2568358">Name Server Operations</a></span></dt>
  55 <dd><dl>
  56 <dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2568363">Tools for Use With the Name Server Daemon</a></span></dt>
  57 <dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2570124">Signals</a></span></dt>
  58 </dl></dd>
  59 </dl>
  60 </div>
  61 <p>
  62       In this chapter we provide some suggested configurations along
  63       with guidelines for their use.  We suggest reasonable values for
  64       certain option settings.
  65     </p>
  66 <div class="sect1" lang="en">
  67 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  68 <a name="sample_configuration"></a>Sample Configurations</h2></div></div></div>
  69 <div class="sect2" lang="en">
  70 <div class="titlepage"><div><div><h3 class="title">
  71 <a name="id2567897"></a>A Caching-only Name Server</h3></div></div></div>
  72 <p>
  73           The following sample configuration is appropriate for a caching-only
  74           name server for use by clients internal to a corporation.  All
  75           queries
  76           from outside clients are refused using the <span><strong class="command">allow-query</strong></span>
  77           option.  Alternatively, the same effect could be achieved using
  78           suitable
  79           firewall rules.
  80         </p>
  81 <pre class="programlisting">
  82 // Two corporate subnets we wish to allow queries from.
  83 acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
  84 options {
  85      // Working directory
  86      directory "/etc/namedb";
  87
  88      allow-query { corpnets; };
  89 };
  90 // Provide a reverse mapping for the loopback
  91 // address 127.0.0.1
  92 zone "0.0.127.in-addr.arpa" {
  93      type master;
  94      file "localhost.rev";
  95      notify no;
  96 };
  97 </pre>
  98 </div>
  99 <div class="sect2" lang="en">
 100 <div class="titlepage"><div><div><h3 class="title">
 101 <a name="id2567913"></a>An Authoritative-only Name Server</h3></div></div></div>
 102 <p>
 103           This sample configuration is for an authoritative-only server
 104           that is the master server for "<code class="filename">example.com</code>"
 105           and a slave for the subdomain "<code class="filename">eng.example.com</code>".
 106         </p>
 107 <pre class="programlisting">
 108 options {
 109      // Working directory
 110      directory "/etc/namedb";
 111      // Do not allow access to cache
 112      allow-query-cache { none; };
 113      // This is the default
 114      allow-query { any; };
 115      // Do not provide recursive service
 116      recursion no;
 117 };
 118
 119 // Provide a reverse mapping for the loopback
 120 // address 127.0.0.1
 121 zone "0.0.127.in-addr.arpa" {
 122      type master;
 123      file "localhost.rev";
 124      notify no;
 125 };
 126 // We are the master server for example.com
 127 zone "example.com" {
 128      type master;
 129      file "example.com.db";
 130      // IP addresses of slave servers allowed to
 131      // transfer example.com
 132      allow-transfer {
 133           192.168.4.14;
 134           192.168.5.53;
 135      };
 136 };
 137 // We are a slave server for eng.example.com
 138 zone "eng.example.com" {
 139      type slave;
 140      file "eng.example.com.bk";
 141      // IP address of eng.example.com master server
 142      masters { 192.168.4.12; };
 143 };
 144 </pre>
 145 </div>
 146 </div>
 147 <div class="sect1" lang="en">
 148 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 149 <a name="id2568004"></a>Load Balancing</h2></div></div></div>
 150 <p>
 151         A primitive form of load balancing can be achieved in
 152         the <acronym class="acronym">DNS</acronym> by using multiple records
 153         (such as multiple A records) for one name.
 154       </p>
 155 <p>
 156         For example, if you have three WWW servers with network addresses
 157         of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the
 158         following means that clients will connect to each machine one third
 159         of the time:
 160       </p>
 161 <div class="informaltable"><table border="1">
 162 <colgroup>
 163 <col>
 164 <col>
 165 <col>
 166 <col>
 167 <col>
 168 </colgroup>
 169 <tbody>
 170 <tr>
 171 <td>
 172                 <p>
 173                   Name
 174                 </p>
 175               </td>
 176 <td>
 177                 <p>
 178                   TTL
 179                 </p>
 180               </td>
 181 <td>
 182                 <p>
 183                   CLASS
 184                 </p>
 185               </td>
 186 <td>
 187                 <p>
 188                   TYPE
 189                 </p>
 190               </td>
 191 <td>
 192                 <p>
 193                   Resource Record (RR) Data
 194                 </p>
 195               </td>
 196 </tr>
 197 <tr>
 198 <td>
 199                 <p>
 200                   <code class="literal">www</code>
 201                 </p>
 202               </td>
 203 <td>
 204                 <p>
 205                   <code class="literal">600</code>
 206                 </p>
 207               </td>
 208 <td>
 209                 <p>
 210                   <code class="literal">IN</code>
 211                 </p>
 212               </td>
 213 <td>
 214                 <p>
 215                   <code class="literal">A</code>
 216                 </p>
 217               </td>
 218 <td>
 219                 <p>
 220                   <code class="literal">10.0.0.1</code>
 221                 </p>
 222               </td>
 223 </tr>
 224 <tr>
 225 <td>
 226                 <p></p>
 227               </td>
 228 <td>
 229                 <p>
 230                   <code class="literal">600</code>
 231                 </p>
 232               </td>
 233 <td>
 234                 <p>
 235                   <code class="literal">IN</code>
 236                 </p>
 237               </td>
 238 <td>
 239                 <p>
 240                   <code class="literal">A</code>
 241                 </p>
 242               </td>
 243 <td>
 244                 <p>
 245                   <code class="literal">10.0.0.2</code>
 246                 </p>
 247               </td>
 248 </tr>
 249 <tr>
 250 <td>
 251                 <p></p>
 252               </td>
 253 <td>
 254                 <p>
 255                   <code class="literal">600</code>
 256                 </p>
 257               </td>
 258 <td>
 259                 <p>
 260                   <code class="literal">IN</code>
 261                 </p>
 262               </td>
 263 <td>
 264                 <p>
 265                   <code class="literal">A</code>
 266                 </p>
 267               </td>
 268 <td>
 269                 <p>
 270                   <code class="literal">10.0.0.3</code>
 271                 </p>
 272               </td>
 273 </tr>
 274 </tbody>
 275 </table></div>
 276 <p>
 277         When a resolver queries for these records, <acronym class="acronym">BIND</acronym> will rotate
 278         them and respond to the query with the records in a different
 279         order.  In the example above, clients will randomly receive
 280         records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients
 281         will use the first record returned and discard the rest.
 282       </p>
 283 <p>
 284         For more detail on ordering responses, check the
 285         <span><strong class="command">rrset-order</strong></span> substatement in the
 286         <span><strong class="command">options</strong></span> statement, see
 287         <a href="Bv9ARM.ch06.html#rrset_ordering">RRset Ordering</a>.
 288       </p>
 289 </div>
 290 <div class="sect1" lang="en">
 291 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 292 <a name="id2568358"></a>Name Server Operations</h2></div></div></div>
 293 <div class="sect2" lang="en">
 294 <div class="titlepage"><div><div><h3 class="title">
 295 <a name="id2568363"></a>Tools for Use With the Name Server Daemon</h3></div></div></div>
 296 <p>
 297           This section describes several indispensable diagnostic,
 298           administrative and monitoring tools available to the system
 299           administrator for controlling and debugging the name server
 300           daemon.
 301         </p>
 302 <div class="sect3" lang="en">
 303 <div class="titlepage"><div><div><h4 class="title">
 304 <a name="diagnostic_tools"></a>Diagnostic Tools</h4></div></div></div>
 305 <p>
 306             The <span><strong class="command">dig</strong></span>, <span><strong class="command">host</strong></span>, and
 307             <span><strong class="command">nslookup</strong></span> programs are all command
 308             line tools
 309             for manually querying name servers.  They differ in style and
 310             output format.
 311           </p>
 312 <div class="variablelist"><dl>
 313 <dt><span class="term"><a name="dig"></a><span><strong class="command">dig</strong></span></span></dt>
 314 <dd>
 315 <p>
 316                   The domain information groper (<span><strong class="command">dig</strong></span>)
 317                   is the most versatile and complete of these lookup tools.
 318                   It has two modes: simple interactive
 319                   mode for a single query, and batch mode which executes a
 320                   query for
 321                   each in a list of several query lines. All query options are
 322                   accessible
 323                   from the command line.
 324                 </p>
 325 <div class="cmdsynopsis"><p><code class="command">dig</code>  [@<em class="replaceable"><code>server</code></em>]  <em class="replaceable"><code>domain</code></em>  [<em class="replaceable"><code>query-type</code></em>] [<em class="replaceable"><code>query-class</code></em>] [+<em class="replaceable"><code>query-option</code></em>] [-<em class="replaceable"><code>dig-option</code></em>] [%<em class="replaceable"><code>comment</code></em>]</p></div>
 326 <p>
 327                   The usual simple use of <span><strong class="command">dig</strong></span> will take the form
 328                 </p>
 329 <p>
 330                   <span><strong class="command">dig @server domain query-type query-class</strong></span>
 331                 </p>
 332 <p>
 333                   For more information and a list of available commands and
 334                   options, see the <span><strong class="command">dig</strong></span> man
 335                   page.
 336                 </p>
 337 </dd>
 338 <dt><span class="term"><span><strong class="command">host</strong></span></span></dt>
 339 <dd>
 340 <p>
 341                   The <span><strong class="command">host</strong></span> utility emphasizes
 342                   simplicity
 343                   and ease of use.  By default, it converts
 344                   between host names and Internet addresses, but its
 345                   functionality
 346                   can be extended with the use of options.
 347                 </p>
 348 <div class="cmdsynopsis"><p><code class="command">host</code>  [-aCdlnrsTwv] [-c <em class="replaceable"><code>class</code></em>] [-N <em class="replaceable"><code>ndots</code></em>] [-t <em class="replaceable"><code>type</code></em>] [-W <em class="replaceable"><code>timeout</code></em>] [-R <em class="replaceable"><code>retries</code></em>] [-m <em class="replaceable"><code>flag</code></em>] [-4] [-6]  <em class="replaceable"><code>hostname</code></em>  [<em class="replaceable"><code>server</code></em>]</p></div>
 349 <p>
 350                   For more information and a list of available commands and
 351                   options, see the <span><strong class="command">host</strong></span> man
 352                   page.
 353                 </p>
 354 </dd>
 355 <dt><span class="term"><span><strong class="command">nslookup</strong></span></span></dt>
 356 <dd>
 357 <p><span><strong class="command">nslookup</strong></span>
 358                   has two modes: interactive and
 359                   non-interactive. Interactive mode allows the user to
 360                   query name servers for information about various
 361                   hosts and domains or to print a list of hosts in a
 362                   domain. Non-interactive mode is used to print just
 363                   the name and requested information for a host or
 364                   domain.
 365                 </p>
 366 <div class="cmdsynopsis"><p><code class="command">nslookup</code>  [-option...] [[<em class="replaceable"><code>host-to-find</code></em>] |  [- [server]]]</p></div>
 367 <p>
 368                   Interactive mode is entered when no arguments are given (the
 369                   default name server will be used) or when the first argument
 370                   is a
 371                   hyphen (`-') and the second argument is the host name or
 372                   Internet address
 373                   of a name server.
 374                 </p>
 375 <p>
 376                   Non-interactive mode is used when the name or Internet
 377                   address
 378                   of the host to be looked up is given as the first argument.
 379                   The
 380                   optional second argument specifies the host name or address
 381                   of a name server.
 382                 </p>
 383 <p>
 384                   Due to its arcane user interface and frequently inconsistent
 385                   behavior, we do not recommend the use of <span><strong class="command">nslookup</strong></span>.
 386                   Use <span><strong class="command">dig</strong></span> instead.
 387                 </p>
 388 </dd>
 389 </dl></div>
 390 </div>
 391 <div class="sect3" lang="en">
 392 <div class="titlepage"><div><div><h4 class="title">
 393 <a name="admin_tools"></a>Administrative Tools</h4></div></div></div>
 394 <p>
 395             Administrative tools play an integral part in the management
 396             of a server.
 397           </p>
 398 <div class="variablelist"><dl>
 399 <dt>
 400 <a name="named-checkconf"></a><span class="term"><span><strong class="command">named-checkconf</strong></span></span>
 401 </dt>
 402 <dd>
 403 <p>
 404                   The <span><strong class="command">named-checkconf</strong></span> program
 405                   checks the syntax of a <code class="filename">named.conf</code> file.
 406                 </p>
 407 <div class="cmdsynopsis"><p><code class="command">named-checkconf</code>  [-jvz] [-t <em class="replaceable"><code>directory</code></em>] [<em class="replaceable"><code>filename</code></em>]</p></div>
 408 </dd>
 409 <dt>
 410 <a name="named-checkzone"></a><span class="term"><span><strong class="command">named-checkzone</strong></span></span>
 411 </dt>
 412 <dd>
 413 <p>
 414                   The <span><strong class="command">named-checkzone</strong></span> program
 415                   checks a master file for
 416                   syntax and consistency.
 417                 </p>
 418 <div class="cmdsynopsis"><p><code class="command">named-checkzone</code>  [-djqvD] [-c <em class="replaceable"><code>class</code></em>] [-o <em class="replaceable"><code>output</code></em>] [-t <em class="replaceable"><code>directory</code></em>] [-w <em class="replaceable"><code>directory</code></em>] [-k <em class="replaceable"><code>(ignore|warn|fail)</code></em>] [-n <em class="replaceable"><code>(ignore|warn|fail)</code></em>] [-W <em class="replaceable"><code>(ignore|warn)</code></em>]  <em class="replaceable"><code>zone</code></em>  [<em class="replaceable"><code>filename</code></em>]</p></div>
 419 </dd>
 420 <dt>
 421 <a name="named-compilezone"></a><span class="term"><span><strong class="command">named-compilezone</strong></span></span>
 422 </dt>
 423 <dd><p>
 424                   Similar to <span><strong class="command">named-checkzone,</strong></span> but
 425                   it always dumps the zone content to a specified file
 426                   (typically in a different format).
 427                 </p></dd>
 428 <dt>
 429 <a name="rndc"></a><span class="term"><span><strong class="command">rndc</strong></span></span>
 430 </dt>
 431 <dd>
 432 <p>
 433                   The remote name daemon control
 434                   (<span><strong class="command">rndc</strong></span>) program allows the
 435                   system
 436                   administrator to control the operation of a name server.
 437                   Since <acronym class="acronym">BIND</acronym> 9.2, <span><strong class="command">rndc</strong></span>
 438                   supports all the commands of the BIND 8 <span><strong class="command">ndc</strong></span>
 439                   utility except <span><strong class="command">ndc start</strong></span> and
 440                   <span><strong class="command">ndc restart</strong></span>, which were also
 441                   not supported in <span><strong class="command">ndc</strong></span>'s
 442                   channel mode.
 443                   If you run <span><strong class="command">rndc</strong></span> without any
 444                   options
 445                   it will display a usage message as follows:
 446                 </p>
 447 <div class="cmdsynopsis"><p><code class="command">rndc</code>  [-c <em class="replaceable"><code>config</code></em>] [-s <em class="replaceable"><code>server</code></em>] [-p <em class="replaceable"><code>port</code></em>] [-y <em class="replaceable"><code>key</code></em>]  <em class="replaceable"><code>command</code></em>  [<em class="replaceable"><code>command</code></em>...]</p></div>
 448 <p>The <span><strong class="command">command</strong></span>
 449                   is one of the following:
 450                 </p>
 451 <div class="variablelist"><dl>
 452 <dt><span class="term"><strong class="userinput"><code>reload</code></strong></span></dt>
 453 <dd><p>
 454                         Reload configuration file and zones.
 455                       </p></dd>
 456 <dt><span class="term"><strong class="userinput"><code>reload <em class="replaceable"><code>zone</code></em>
 457                         [<span class="optional"><em class="replaceable"><code>class</code></em>
 458            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
 459 <dd><p>
 460                         Reload the given zone.
 461                       </p></dd>
 462 <dt><span class="term"><strong class="userinput"><code>refresh <em class="replaceable"><code>zone</code></em>
 463                         [<span class="optional"><em class="replaceable"><code>class</code></em>
 464            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
 465 <dd><p>
 466                         Schedule zone maintenance for the given zone.
 467                       </p></dd>
 468 <dt><span class="term"><strong class="userinput"><code>retransfer <em class="replaceable"><code>zone</code></em>
 469
 470                         [<span class="optional"><em class="replaceable"><code>class</code></em>
 471            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
 472 <dd><p>
 473                         Retransfer the given zone from the master.
 474                       </p></dd>
 475 <dt><span class="term"><strong class="userinput"><code>sign <em class="replaceable"><code>zone</code></em>
 476                         [<span class="optional"><em class="replaceable"><code>class</code></em>
 477            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
 478 <dd>
 479 <p>
 480                         Fetch all DNSSEC keys for the given zone
 481                         from the key directory (see
 482                         <span><strong class="command">key-directory</strong></span> in
 483                         <a href="Bv9ARM.ch06.html#options" title="options Statement Definition and
 484           Usage">the section called &#8220;<span><strong class="command">options</strong></span> Statement Definition and
 485           Usage&#8221;</a>), and merge them
 486                         into the zone's DNSKEY RRset.  If the DNSKEY RRset
 487                         is changed as a result of this, then the zone is
 488                         automatically re-signed with the new key set.
 489                       </p>
 490 <p>
 491                         This command requires that the
 492                         <span><strong class="command">auto-dnssec</strong></span> zone option to be set
 493                         to <code class="literal">allow</code>,
 494                         <code class="literal">maintain</code>, or
 495                         <code class="literal">create</code>,  and also requires
 496                         the zone to be configured to allow dynamic DNS.
 497                         See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called &#8220;Dynamic Update Policies&#8221;</a> for
 498                         more details.
 499                       </p>
 500 </dd>
 501 <dt><span class="term"><strong class="userinput"><code>freeze
 502                         [<span class="optional"><em class="replaceable"><code>zone</code></em>
 503        [<span class="optional"><em class="replaceable"><code>class</code></em>
 504            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
 505 <dd><p>
 506                         Suspend updates to a dynamic zone.  If no zone is
 507                         specified,
 508                         then all zones are suspended.  This allows manual
 509                         edits to be made to a zone normally updated by dynamic
 510                         update.  It
 511                         also causes changes in the journal file to be synced
 512                         into the master
 513                         and the journal file to be removed.  All dynamic
 514                         update attempts will
 515                         be refused while the zone is frozen.
 516                       </p></dd>
 517 <dt><span class="term"><strong class="userinput"><code>thaw
 518                         [<span class="optional"><em class="replaceable"><code>zone</code></em>
 519        [<span class="optional"><em class="replaceable"><code>class</code></em>
 520            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
 521 <dd><p>
 522                         Enable updates to a frozen dynamic zone.  If no zone
 523                         is
 524                         specified, then all frozen zones are enabled.  This
 525                         causes
 526                         the server to reload the zone from disk, and
 527                         re-enables dynamic updates
 528                         after the load has completed.  After a zone is thawed,
 529                         dynamic updates
 530                         will no longer be refused.
 531                       </p></dd>
 532 <dt><span class="term"><strong class="userinput"><code>notify <em class="replaceable"><code>zone</code></em>
 533                         [<span class="optional"><em class="replaceable"><code>class</code></em>
 534            [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
 535 <dd><p>
 536                         Resend NOTIFY messages for the zone.
 537                       </p></dd>
 538 <dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt>
 539 <dd><p>
 540                         Reload the configuration file and load new zones,
 541                         but do not reload existing zone files even if they
 542                         have changed.
 543                         This is faster than a full <span><strong class="command">reload</strong></span> when there
 544                         is a large number of zones because it avoids the need
 545                         to examine the
 546                         modification times of the zones files.
 547                       </p></dd>
 548 <dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt>
 549 <dd><p>
 550                         Write server statistics to the statistics file.
 551                       </p></dd>
 552 <dt><span class="term"><strong class="userinput"><code>querylog</code></strong></span></dt>
 553 <dd><p>
 554                         Toggle query logging. Query logging can also be enabled
 555                         by explicitly directing the <span><strong class="command">queries</strong></span>
 556                         <span><strong class="command">category</strong></span> to a
 557                         <span><strong class="command">channel</strong></span> in the
 558                         <span><strong class="command">logging</strong></span> section of
 559                         <code class="filename">named.conf</code> or by specifying
 560                         <span><strong class="command">querylog yes;</strong></span> in the
 561                         <span><strong class="command">options</strong></span> section of
 562                         <code class="filename">named.conf</code>.
 563                       </p></dd>
 564 <dt><span class="term"><strong class="userinput"><code>dumpdb
 565                         [<span class="optional">-all|-cache|-zone</span>]
 566                         [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
 567 <dd><p>
 568                         Dump the server's caches (default) and/or zones to
 569                         the
 570                         dump file for the specified views.  If no view is
 571                         specified, all
 572                         views are dumped.
 573                       </p></dd>
 574 <dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt>
 575 <dd><p>
 576                         Stop the server, making sure any recent changes
 577                         made through dynamic update or IXFR are first saved to
 578                         the master files of the updated zones.
 579                         If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
 580                         This allows an external process to determine when <span><strong class="command">named</strong></span>
 581                         had completed stopping.
 582                       </p></dd>
 583 <dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt>
 584 <dd><p>
 585                         Stop the server immediately.  Recent changes
 586                         made through dynamic update or IXFR are not saved to
 587                         the master files, but will be rolled forward from the
 588                         journal files when the server is restarted.
 589                         If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
 590                         This allows an external process to determine when <span><strong class="command">named</strong></span>
 591                         had completed halting.
 592                       </p></dd>
 593 <dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt>
 594 <dd><p>
 595                         Increment the servers debugging level by one.
 596                       </p></dd>
 597 <dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt>
 598 <dd><p>
 599                         Sets the server's debugging level to an explicit
 600                         value.
 601                       </p></dd>
 602 <dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt>
 603 <dd><p>
 604                         Sets the server's debugging level to 0.
 605                       </p></dd>
 606 <dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt>
 607 <dd><p>
 608                         Flushes the server's cache.
 609                       </p></dd>
 610 <dt><span class="term"><strong class="userinput"><code>flushname</code></strong> <em class="replaceable"><code>name</code></em></span></dt>
 611 <dd><p>
 612                         Flushes the given name from the server's cache.
 613                       </p></dd>
 614 <dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt>
 615 <dd><p>
 616                         Display status of the server.
 617                         Note that the number of zones includes the internal <span><strong class="command">bind/CH</strong></span> zone
 618                         and the default <span><strong class="command">./IN</strong></span>
 619                         hint zone if there is not an
 620                         explicit root zone configured.
 621                       </p></dd>
 622 <dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt>
 623 <dd><p>
 624                         Dump the list of queries <span><strong class="command">named</strong></span> is currently recursing
 625                         on.
 626                       </p></dd>
 627 <dt><span class="term"><strong class="userinput"><code>validation
 628                         [<span class="optional">on|off</span>]
 629                         [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]
 630                     </code></strong></span></dt>
 631 <dd><p>
 632                         Enable or disable DNSSEC validation.
 633                         Note <span><strong class="command">dnssec-enable</strong></span> also needs to be
 634                         set to <strong class="userinput"><code>yes</code></strong> to be effective.
 635                         It defaults to enabled.
 636                       </p></dd>
 637 </dl></div>
 638 <p>
 639                   A configuration file is required, since all
 640                   communication with the server is authenticated with
 641                   digital signatures that rely on a shared secret, and
 642                   there is no way to provide that secret other than with a
 643                   configuration file.  The default location for the
 644                   <span><strong class="command">rndc</strong></span> configuration file is
 645                   <code class="filename">/etc/rndc.conf</code>, but an
 646                   alternate
 647                   location can be specified with the <code class="option">-c</code>
 648                   option.  If the configuration file is not found,
 649                   <span><strong class="command">rndc</strong></span> will also look in
 650                   <code class="filename">/etc/rndc.key</code> (or whatever
 651                   <code class="varname">sysconfdir</code> was defined when
 652                   the <acronym class="acronym">BIND</acronym> build was
 653                   configured).
 654                   The <code class="filename">rndc.key</code> file is
 655                   generated by
 656                   running <span><strong class="command">rndc-confgen -a</strong></span> as
 657                   described in
 658                   <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and
 659           Usage">the section called &#8220;<span><strong class="command">controls</strong></span> Statement Definition and
 660           Usage&#8221;</a>.
 661                 </p>
 662 <p>
 663                   The format of the configuration file is similar to
 664                   that of <code class="filename">named.conf</code>, but
 665                   limited to
 666                   only four statements, the <span><strong class="command">options</strong></span>,
 667                   <span><strong class="command">key</strong></span>, <span><strong class="command">server</strong></span> and
 668                   <span><strong class="command">include</strong></span>
 669                   statements.  These statements are what associate the
 670                   secret keys to the servers with which they are meant to
 671                   be shared.  The order of statements is not
 672                   significant.
 673                 </p>
 674 <p>
 675                   The <span><strong class="command">options</strong></span> statement has
 676                   three clauses:
 677                   <span><strong class="command">default-server</strong></span>, <span><strong class="command">default-key</strong></span>,
 678                   and <span><strong class="command">default-port</strong></span>.
 679                   <span><strong class="command">default-server</strong></span> takes a
 680                   host name or address argument  and represents the server
 681                   that will
 682                   be contacted if no <code class="option">-s</code>
 683                   option is provided on the command line.
 684                   <span><strong class="command">default-key</strong></span> takes
 685                   the name of a key as its argument, as defined by a <span><strong class="command">key</strong></span> statement.
 686                   <span><strong class="command">default-port</strong></span> specifies the
 687                   port to which
 688                   <span><strong class="command">rndc</strong></span> should connect if no
 689                   port is given on the command line or in a
 690                   <span><strong class="command">server</strong></span> statement.
 691                 </p>
 692 <p>
 693                   The <span><strong class="command">key</strong></span> statement defines a
 694                   key to be used
 695                   by <span><strong class="command">rndc</strong></span> when authenticating
 696                   with
 697                   <span><strong class="command">named</strong></span>.  Its syntax is
 698                   identical to the
 699                   <span><strong class="command">key</strong></span> statement in <code class="filename">named.conf</code>.
 700                   The keyword <strong class="userinput"><code>key</code></strong> is
 701                   followed by a key name, which must be a valid
 702                   domain name, though it need not actually be hierarchical;
 703                   thus,
 704                   a string like "<strong class="userinput"><code>rndc_key</code></strong>" is a valid
 705                   name.
 706                   The <span><strong class="command">key</strong></span> statement has two
 707                   clauses:
 708                   <span><strong class="command">algorithm</strong></span> and <span><strong class="command">secret</strong></span>.
 709                   While the configuration parser will accept any string as the
 710                   argument
 711                   to algorithm, currently only the string "<strong class="userinput"><code>hmac-md5</code></strong>"
 712                   has any meaning.  The secret is a base-64 encoded string
 713                   as specified in RFC 3548.
 714                 </p>
 715 <p>
 716                   The <span><strong class="command">server</strong></span> statement
 717                   associates a key
 718                   defined using the <span><strong class="command">key</strong></span>
 719                   statement with a server.
 720                   The keyword <strong class="userinput"><code>server</code></strong> is followed by a
 721                   host name or address.  The <span><strong class="command">server</strong></span> statement
 722                   has two clauses: <span><strong class="command">key</strong></span> and <span><strong class="command">port</strong></span>.
 723                   The <span><strong class="command">key</strong></span> clause specifies the
 724                   name of the key
 725                   to be used when communicating with this server, and the
 726                   <span><strong class="command">port</strong></span> clause can be used to
 727                   specify the port <span><strong class="command">rndc</strong></span> should
 728                   connect
 729                   to on the server.
 730                 </p>
 731 <p>
 732                   A sample minimal configuration file is as follows:
 733                 </p>
 734 <pre class="programlisting">
 735 key rndc_key {
 736      algorithm "hmac-md5";
 737      secret
 738        "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
 739 };
 740 options {
 741      default-server 127.0.0.1;
 742      default-key    rndc_key;
 743 };
 744 </pre>
 745 <p>
 746                   This file, if installed as <code class="filename">/etc/rndc.conf</code>,
 747                   would allow the command:
 748                 </p>
 749 <p>
 750                   <code class="prompt">$ </code><strong class="userinput"><code>rndc reload</code></strong>
 751                 </p>
 752 <p>
 753                   to connect to 127.0.0.1 port 953 and cause the name server
 754                   to reload, if a name server on the local machine were
 755                   running with
 756                   following controls statements:
 757                 </p>
 758 <pre class="programlisting">
 759 controls {
 760         inet 127.0.0.1
 761             allow { localhost; } keys { rndc_key; };
 762 };
 763 </pre>
 764 <p>
 765                   and it had an identical key statement for
 766                   <code class="literal">rndc_key</code>.
 767                 </p>
 768 <p>
 769                   Running the <span><strong class="command">rndc-confgen</strong></span>
 770                   program will
 771                   conveniently create a <code class="filename">rndc.conf</code>
 772                   file for you, and also display the
 773                   corresponding <span><strong class="command">controls</strong></span>
 774                   statement that you need to
 775                   add to <code class="filename">named.conf</code>.
 776                   Alternatively,
 777                   you can run <span><strong class="command">rndc-confgen -a</strong></span>
 778                   to set up
 779                   a <code class="filename">rndc.key</code> file and not
 780                   modify
 781                   <code class="filename">named.conf</code> at all.
 782                 </p>
 783 </dd>
 784 </dl></div>
 785 </div>
 786 </div>
 787 <div class="sect2" lang="en">
 788 <div class="titlepage"><div><div><h3 class="title">
 789 <a name="id2570124"></a>Signals</h3></div></div></div>
 790 <p>
 791           Certain UNIX signals cause the name server to take specific
 792           actions, as described in the following table.  These signals can
 793           be sent using the <span><strong class="command">kill</strong></span> command.
 794         </p>
 795 <div class="informaltable"><table border="1">
 796 <colgroup>
 797 <col>
 798 <col>
 799 </colgroup>
 800 <tbody>
 801 <tr>
 802 <td>
 803                   <p><span><strong class="command">SIGHUP</strong></span></p>
 804                 </td>
 805 <td>
 806                   <p>
 807                     Causes the server to read <code class="filename">named.conf</code> and
 808                     reload the database.
 809                   </p>
 810                 </td>
 811 </tr>
 812 <tr>
 813 <td>
 814                   <p><span><strong class="command">SIGTERM</strong></span></p>
 815                 </td>
 816 <td>
 817                   <p>
 818                     Causes the server to clean up and exit.
 819                   </p>
 820                 </td>
 821 </tr>
 822 <tr>
 823 <td>
 824                   <p><span><strong class="command">SIGINT</strong></span></p>
 825                 </td>
 826 <td>
 827                   <p>
 828                     Causes the server to clean up and exit.
 829                   </p>
 830                 </td>
 831 </tr>
 832 </tbody>
 833 </table></div>
 834 </div>
 835 </div>
 836 </div>
 837 <div class="navfooter">
 838 <hr>
 839 <table width="100%" summary="Navigation footer">
 840 <tr>
 841 <td width="40%" align="left">
 842 <a accesskey="p" href="Bv9ARM.ch02.html">Prev</a> </td>
 843 <td width="20%" align="center"> </td>
 844 <td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch04.html">Next</a>
 845 </td>
 846 </tr>
 847 <tr>
 848 <td width="40%" align="left" valign="top">Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements </td>
 849 <td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
 850 <td width="40%" align="right" valign="top"> Chapter 4. Advanced DNS Features</td>
 851 </tr>
 852 </table>
 853 </div>
 854 </body>
 855 </html>