PageRenderTime 111ms CodeModel.GetById 75ms app.highlight 26ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/bind9/doc/arm/Bv9ARM.ch03.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 957 lines | 937 code | 3 blank | 17 comment | 0 complexity | 56fd8847e44f89610f3762515d6c063e MD5 | raw file
  1<!--
  2 - Copyright (C) 2004-2012 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$ -->
 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#id2567771">A Caching-only Name Server</a></span></dt>
 51<dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2567992">An Authoritative-only Name Server</a></span></dt>
 52</dl></dd>
 53<dt><span class="sect1"><a href="Bv9ARM.ch03.html#id2568014">Load Balancing</a></span></dt>
 54<dt><span class="sect1"><a href="Bv9ARM.ch03.html#id2568369">Name Server Operations</a></span></dt>
 55<dd><dl>
 56<dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2568374">Tools for Use With the Name Server Daemon</a></span></dt>
 57<dt><span class="sect2"><a href="Bv9ARM.ch03.html#id2570421">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="id2567771"></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.
 83acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
 84options {
 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
 92zone "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="id2567992"></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">
108options {
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
121zone "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
127zone "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
138zone "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="id2568014"></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> sub-statement 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="id2568369"></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="id2568374"></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>).  If they are within
486                        their publication period, merge them into the
487                        zone's DNSKEY RRset.  If the DNSKEY RRset
488                        is changed, then the zone is automatically
489                        re-signed with the new key set.
490                      </p>
491<p>
492                        This command requires that the
493                        <span><strong class="command">auto-dnssec</strong></span> zone option be set
494                        to <code class="literal">allow</code> or
495                        <code class="literal">maintain</code>,
496                        and also requires the zone to be configured to
497                        allow dynamic DNS.
498                        See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called &#8220;Dynamic Update Policies&#8221;</a> for
499                        more details.
500                      </p>
501</dd>
502<dt><span class="term"><strong class="userinput"><code>loadkeys <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>]</code></strong></span></dt>
505<dd>
506<p>
507                        Fetch all DNSSEC keys for the given zone
508                        from the key directory (see
509                        <span><strong class="command">key-directory</strong></span> in
510                        <a href="Bv9ARM.ch06.html#options" title="options Statement Definition and
511          Usage">the section called &#8220;<span><strong class="command">options</strong></span> Statement Definition and
512          Usage&#8221;</a>).  If they are within
513                        their publication period, merge them into the
514                        zone's DNSKEY RRset.  Unlike <span><strong class="command">rndc
515                        sign</strong></span>, however, the zone is not
516                        immediately re-signed by the new keys, but is
517                        allowed to incrementally re-sign over time.
518                      </p>
519<p>
520                        This command requires that the
521                        <span><strong class="command">auto-dnssec</strong></span> zone option
522                        be set to <code class="literal">maintain</code>,
523                        and also requires the zone to be configured to
524                        allow dynamic DNS.
525                        See <a href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called &#8220;Dynamic Update Policies&#8221;</a> for
526                        more details.
527                      </p>
528</dd>
529<dt><span class="term"><strong class="userinput"><code>freeze
530                        [<span class="optional"><em class="replaceable"><code>zone</code></em>
531       [<span class="optional"><em class="replaceable"><code>class</code></em>
532           [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
533<dd><p>
534                        Suspend updates to a dynamic zone.  If no zone is
535                        specified,
536                        then all zones are suspended.  This allows manual
537                        edits to be made to a zone normally updated by dynamic
538                        update.  It
539                        also causes changes in the journal file to be synced
540                        into the master
541                        and the journal file to be removed.  All dynamic
542                        update attempts will
543                        be refused while the zone is frozen.
544                      </p></dd>
545<dt><span class="term"><strong class="userinput"><code>thaw
546                        [<span class="optional"><em class="replaceable"><code>zone</code></em>
547       [<span class="optional"><em class="replaceable"><code>class</code></em>
548           [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
549<dd><p>
550                        Enable updates to a frozen dynamic zone.  If no zone
551                        is
552                        specified, then all frozen zones are enabled.  This
553                        causes
554                        the server to reload the zone from disk, and
555                        re-enables dynamic updates
556                        after the load has completed.  After a zone is thawed,
557                        dynamic updates
558                        will no longer be refused.
559                      </p></dd>
560<dt><span class="term"><strong class="userinput"><code>notify <em class="replaceable"><code>zone</code></em>
561                        [<span class="optional"><em class="replaceable"><code>class</code></em>
562           [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
563<dd><p>
564                        Resend NOTIFY messages for the zone.
565                      </p></dd>
566<dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt>
567<dd><p>
568                        Reload the configuration file and load new zones,
569                        but do not reload existing zone files even if they
570                        have changed.
571                        This is faster than a full <span><strong class="command">reload</strong></span> when there
572                        is a large number of zones because it avoids the need
573                        to examine the
574                        modification times of the zones files.
575                      </p></dd>
576<dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt>
577<dd><p>
578                        Write server statistics to the statistics file.
579                      </p></dd>
580<dt><span class="term"><strong class="userinput"><code>querylog</code></strong></span></dt>
581<dd><p>
582                        Toggle query logging. Query logging can also be enabled
583                        by explicitly directing the <span><strong class="command">queries</strong></span>
584                        <span><strong class="command">category</strong></span> to a
585                        <span><strong class="command">channel</strong></span> in the
586                        <span><strong class="command">logging</strong></span> section of
587                        <code class="filename">named.conf</code> or by specifying
588                        <span><strong class="command">querylog yes;</strong></span> in the
589                        <span><strong class="command">options</strong></span> section of
590                        <code class="filename">named.conf</code>.
591                      </p></dd>
592<dt><span class="term"><strong class="userinput"><code>dumpdb
593                        [<span class="optional">-all|-cache|-zone</span>]
594                        [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
595<dd><p>
596                        Dump the server's caches (default) and/or zones to
597                        the
598                        dump file for the specified views.  If no view is
599                        specified, all
600                        views are dumped.
601                      </p></dd>
602<dt><span class="term"><strong class="userinput"><code>secroots
603                        [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
604<dd><p>
605                        Dump the server's security roots to the secroots
606                        file for the specified views.  If no view is
607                        specified, security roots for all
608                        views are dumped.
609                      </p></dd>
610<dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt>
611<dd><p>
612                        Stop the server, making sure any recent changes
613                        made through dynamic update or IXFR are first saved to
614                        the master files of the updated zones.
615                        If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
616                        This allows an external process to determine when <span><strong class="command">named</strong></span>
617                        had completed stopping.
618                      </p></dd>
619<dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt>
620<dd><p>
621                        Stop the server immediately.  Recent changes
622                        made through dynamic update or IXFR are not saved to
623                        the master files, but will be rolled forward from the
624                        journal files when the server is restarted.
625                        If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
626                        This allows an external process to determine when <span><strong class="command">named</strong></span>
627                        had completed halting.
628                      </p></dd>
629<dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt>
630<dd><p>
631                        Increment the servers debugging level by one.
632                      </p></dd>
633<dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt>
634<dd><p>
635                        Sets the server's debugging level to an explicit
636                        value.
637                      </p></dd>
638<dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt>
639<dd><p>
640                        Sets the server's debugging level to 0.
641                      </p></dd>
642<dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt>
643<dd><p>
644                        Flushes the server's cache.
645                      </p></dd>
646<dt><span class="term"><strong class="userinput"><code>flushname</code></strong> <em class="replaceable"><code>name</code></em></span></dt>
647<dd><p>
648                        Flushes the given name from the server's cache.
649                      </p></dd>
650<dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt>
651<dd><p>
652                        Display status of the server.
653                        Note that the number of zones includes the internal <span><strong class="command">bind/CH</strong></span> zone
654                        and the default <span><strong class="command">./IN</strong></span>
655                        hint zone if there is not an
656                        explicit root zone configured.
657                      </p></dd>
658<dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt>
659<dd><p>
660                        Dump the list of queries <span><strong class="command">named</strong></span> is currently recursing
661                        on.
662                      </p></dd>
663<dt><span class="term"><strong class="userinput"><code>validation
664                        [<span class="optional">on|off</span>]
665                        [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]
666                    </code></strong></span></dt>
667<dd><p>
668                        Enable or disable DNSSEC validation.
669                        Note <span><strong class="command">dnssec-enable</strong></span> also needs to be
670                        set to <strong class="userinput"><code>yes</code></strong> to be effective.
671                        It defaults to enabled.
672                      </p></dd>
673<dt><span class="term"><strong class="userinput"><code>tsig-list</code></strong></span></dt>
674<dd><p>
675                        List the names of all TSIG keys currently configured
676                        for use by <span><strong class="command">named</strong></span> in each view.  The
677                        list both statically configured keys and dynamic
678                        TKEY-negotiated keys.
679                      </p></dd>
680<dt><span class="term"><strong class="userinput"><code>tsig-delete</code></strong>
681                     <em class="replaceable"><code>keyname</code></em>
682                     [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span></dt>
683<dd><p>
684                        Delete a given TKEY-negotated key from the server.
685                        (This does not apply to statically configured TSIG
686                        keys.)
687                      </p></dd>
688<dt><span class="term"><strong class="userinput"><code>addzone
689                        <em class="replaceable"><code>zone</code></em>
690                        [<span class="optional"><em class="replaceable"><code>class</code></em>
691                        [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]
692                        <em class="replaceable"><code>configuration</code></em>
693                    </code></strong></span></dt>
694<dd>
695<p>
696                        Add a zone while the server is running.  This
697                        command requires the
698                        <span><strong class="command">allow-new-zones</strong></span> option to be set
699                        to <strong class="userinput"><code>yes</code></strong>.  The
700                        <em class="replaceable"><code>configuration</code></em> string
701                        specified on the command line is the zone
702                        configuration text that would ordinarily be
703                        placed in <code class="filename">named.conf</code>.
704                      </p>
705<p>
706                        The configuration is saved in a file called
707                       <code class="filename"><em class="replaceable"><code>hash</code></em>.nzf</code>,
708                        where <em class="replaceable"><code>hash</code></em> is a
709                        cryptographic hash generated from the name of
710                        the view.  When <span><strong class="command">named</strong></span> is
711                        restarted, the file will be loaded into the view
712                        configuration, so that zones that were added
713                        can persist after a restart.
714                      </p>
715<p>
716                        This sample <span><strong class="command">addzone</strong></span> command
717                        would add the zone <code class="literal">example.com</code>
718                        to the default view:
719                      </p>
720<p>
721<code class="prompt">$ </code><strong class="userinput"><code>rndc addzone example.com '{ type master; file "example.com.db"; };'</code></strong>
722                      </p>
723<p>
724                        (Note the brackets and semi-colon around the zone
725                        configuration text.)
726                      </p>
727</dd>
728<dt><span class="term"><strong class="userinput"><code>delzone
729                        <em class="replaceable"><code>zone</code></em>
730                        [<span class="optional"><em class="replaceable"><code>class</code></em>
731                        [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]
732                    </code></strong></span></dt>
733<dd><p>
734                        Delete a zone while the server is running.
735                        Only zones that were originally added via
736                        <span><strong class="command">rndc addzone</strong></span> can be deleted
737                        in this matter.
738                      </p></dd>
739</dl></div>
740<p>
741                  A configuration file is required, since all
742                  communication with the server is authenticated with
743                  digital signatures that rely on a shared secret, and
744                  there is no way to provide that secret other than with a
745                  configuration file.  The default location for the
746                  <span><strong class="command">rndc</strong></span> configuration file is
747                  <code class="filename">/etc/rndc.conf</code>, but an
748                  alternate
749                  location can be specified with the <code class="option">-c</code>
750                  option.  If the configuration file is not found,
751                  <span><strong class="command">rndc</strong></span> will also look in
752                  <code class="filename">/etc/rndc.key</code> (or whatever
753                  <code class="varname">sysconfdir</code> was defined when
754                  the <acronym class="acronym">BIND</acronym> build was
755                  configured).
756                  The <code class="filename">rndc.key</code> file is
757                  generated by
758                  running <span><strong class="command">rndc-confgen -a</strong></span> as
759                  described in
760                  <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and
761          Usage">the section called &#8220;<span><strong class="command">controls</strong></span> Statement Definition and
762          Usage&#8221;</a>.
763                </p>
764<p>
765                  The format of the configuration file is similar to
766                  that of <code class="filename">named.conf</code>, but
767                  limited to
768                  only four statements, the <span><strong class="command">options</strong></span>,
769                  <span><strong class="command">key</strong></span>, <span><strong class="command">server</strong></span> and
770                  <span><strong class="command">include</strong></span>
771                  statements.  These statements are what associate the
772                  secret keys to the servers with which they are meant to
773                  be shared.  The order of statements is not
774                  significant.
775                </p>
776<p>
777                  The <span><strong class="command">options</strong></span> statement has
778                  three clauses:
779                  <span><strong class="command">default-server</strong></span>, <span><strong class="command">default-key</strong></span>,
780                  and <span><strong class="command">default-port</strong></span>.
781                  <span><strong class="command">default-server</strong></span> takes a
782                  host name or address argument  and represents the server
783                  that will
784                  be contacted if no <code class="option">-s</code>
785                  option is provided on the command line.
786                  <span><strong class="command">default-key</strong></span> takes
787                  the name of a key as its argument, as defined by a <span><strong class="command">key</strong></span> statement.
788                  <span><strong class="command">default-port</strong></span> specifies the
789                  port to which
790                  <span><strong class="command">rndc</strong></span> should connect if no
791                  port is given on the command line or in a
792                  <span><strong class="command">server</strong></span> statement.
793                </p>
794<p>
795                  The <span><strong class="command">key</strong></span> statement defines a
796                  key to be used
797                  by <span><strong class="command">rndc</strong></span> when authenticating
798                  with
799                  <span><strong class="command">named</strong></span>.  Its syntax is
800                  identical to the
801                  <span><strong class="command">key</strong></span> statement in <code class="filename">named.conf</code>.
802                  The keyword <strong class="userinput"><code>key</code></strong> is
803                  followed by a key name, which must be a valid
804                  domain name, though it need not actually be hierarchical;
805                  thus,
806                  a string like "<strong class="userinput"><code>rndc_key</code></strong>" is a valid
807                  name.
808                  The <span><strong class="command">key</strong></span> statement has two
809                  clauses:
810                  <span><strong class="command">algorithm</strong></span> and <span><strong class="command">secret</strong></span>.
811                  While the configuration parser will accept any string as the
812                  argument
813                  to algorithm, currently only the string "<strong class="userinput"><code>hmac-md5</code></strong>"
814                  has any meaning.  The secret is a base-64 encoded string
815                  as specified in RFC 3548.
816                </p>
817<p>
818                  The <span><strong class="command">server</strong></span> statement
819                  associates a key
820                  defined using the <span><strong class="command">key</strong></span>
821                  statement with a server.
822                  The keyword <strong class="userinput"><code>server</code></strong> is followed by a
823                  host name or address.  The <span><strong class="command">server</strong></span> statement
824                  has two clauses: <span><strong class="command">key</strong></span> and <span><strong class="command">port</strong></span>.
825                  The <span><strong class="command">key</strong></span> clause specifies the
826                  name of the key
827                  to be used when communicating with this server, and the
828                  <span><strong class="command">port</strong></span> clause can be used to
829                  specify the port <span><strong class="command">rndc</strong></span> should
830                  connect
831                  to on the server.
832                </p>
833<p>
834                  A sample minimal configuration file is as follows:
835                </p>
836<pre class="programlisting">
837key rndc_key {
838     algorithm "hmac-md5";
839     secret
840       "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
841};
842options {
843     default-server 127.0.0.1;
844     default-key    rndc_key;
845};
846</pre>
847<p>
848                  This file, if installed as <code class="filename">/etc/rndc.conf</code>,
849                  would allow the command:
850                </p>
851<p>
852                  <code class="prompt">$ </code><strong class="userinput"><code>rndc reload</code></strong>
853                </p>
854<p>
855                  to connect to 127.0.0.1 port 953 and cause the name server
856                  to reload, if a name server on the local machine were
857                  running with
858                  following controls statements:
859                </p>
860<pre class="programlisting">
861controls {
862        inet 127.0.0.1
863            allow { localhost; } keys { rndc_key; };
864};
865</pre>
866<p>
867                  and it had an identical key statement for
868                  <code class="literal">rndc_key</code>.
869                </p>
870<p>
871                  Running the <span><strong class="command">rndc-confgen</strong></span>
872                  program will
873                  conveniently create a <code class="filename">rndc.conf</code>
874                  file for you, and also display the
875                  corresponding <span><strong class="command">controls</strong></span>
876                  statement that you need to
877                  add to <code class="filename">named.conf</code>.
878                  Alternatively,
879                  you can run <span><strong class="command">rndc-confgen -a</strong></span>
880                  to set up
881                  a <code class="filename">rndc.key</code> file and not
882                  modify
883                  <code class="filename">named.conf</code> at all.
884                </p>
885</dd>
886</dl></div>
887</div>
888</div>
889<div class="sect2" lang="en">
890<div class="titlepage"><div><div><h3 class="title">
891<a name="id2570421"></a>Signals</h3></div></div></div>
892<p>
893          Certain UNIX signals cause the name server to take specific
894          actions, as described in the following table.  These signals can
895          be sent using the <span><strong class="command">kill</strong></span> command.
896        </p>
897<div class="informaltable"><table border="1">
898<colgroup>
899<col>
900<col>
901</colgroup>
902<tbody>
903<tr>
904<td>
905                  <p><span><strong class="command">SIGHUP</strong></span></p>
906                </td>
907<td>
908                  <p>
909                    Causes the server to read <code class="filename">named.conf</code> and
910                    reload the database.
911                  </p>
912                </td>
913</tr>
914<tr>
915<td>
916                  <p><span><strong class="command">SIGTERM</strong></span></p>
917                </td>
918<td>
919                  <p>
920                    Causes the server to clean up and exit.
921                  </p>
922                </td>
923</tr>
924<tr>
925<td>
926                  <p><span><strong class="command">SIGINT</strong></span></p>
927                </td>
928<td>
929                  <p>
930                    Causes the server to clean up and exit.
931                  </p>
932                </td>
933</tr>
934</tbody>
935</table></div>
936</div>
937</div>
938</div>
939<div class="navfooter">
940<hr>
941<table width="100%" summary="Navigation footer">
942<tr>
943<td width="40%" align="left">
944<a accesskey="p" href="Bv9ARM.ch02.html">Prev</a> </td>
945<td width="20%" align="center"> </td>
946<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch04.html">Next</a>
947</td>
948</tr>
949<tr>
950<td width="40%" align="left" valign="top">Chapter 2. <acronym class="acronym">BIND</acronym> Resource Requirements </td>
951<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
952<td width="40%" align="right" valign="top"> Chapter 4. Advanced DNS Features</td>
953</tr>
954</table>
955</div>
956</body>
957</html>