Bv9ARM-book.xml 645 KB
Newer Older
1
<!--
Tinderbox User's avatar
Tinderbox User committed
2
 - Copyright (C) 2000-2017  Internet Systems Consortium, Inc. ("ISC")
3
 -
4 5 6
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
7
-->
Tinderbox User's avatar
Tinderbox User committed
8

Evan Hunt's avatar
Evan Hunt committed
9
<!-- Converted by db4-upgrade version 1.0 -->
10
<book xmlns:db="http://docbook.org/ns/docbook" version="5.0">
Evan Hunt's avatar
Evan Hunt committed
11 12
  <info>
    <title>BIND 9 Administrator Reference Manual</title>
13
    <!-- insert copyright start -->
14
    <copyright>
Mark Andrews's avatar
Mark Andrews committed
15 16 17 18
      <year>2000</year>
      <year>2001</year>
      <year>2002</year>
      <year>2003</year>
19 20
      <year>2004</year>
      <year>2005</year>
Mark Andrews's avatar
Mark Andrews committed
21
      <year>2006</year>
Mark Andrews's avatar
Mark Andrews committed
22
      <year>2007</year>
Automatic Updater's avatar
Automatic Updater committed
23
      <year>2008</year>
Automatic Updater's avatar
Automatic Updater committed
24
      <year>2009</year>
Automatic Updater's avatar
Automatic Updater committed
25
      <year>2010</year>
Automatic Updater's avatar
Automatic Updater committed
26
      <year>2011</year>
Automatic Updater's avatar
Automatic Updater committed
27
      <year>2012</year>
Tinderbox User's avatar
Tinderbox User committed
28
      <year>2013</year>
Mark Andrews's avatar
Mark Andrews committed
29
      <year>2014</year>
30
      <year>2015</year>
31
      <year>2016</year>
Tinderbox User's avatar
Tinderbox User committed
32
      <year>2017</year>
33 34
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
35
    <!-- insert copyright end -->
Evan Hunt's avatar
Evan Hunt committed
36 37
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="releaseinfo.xml"/>
  </info>
38

Evan Hunt's avatar
Evan Hunt committed
39
  <chapter xml:id="Bv9ARM.ch01"><info><title>Introduction</title></info>
40

41 42 43 44 45 46 47 48 49 50 51
    <para>
      The Internet Domain Name System (<acronym>DNS</acronym>)
      consists of the syntax
      to specify the names of entities in the Internet in a hierarchical
      manner, the rules used for delegating authority over names, and the
      system implementation that actually maps names to Internet
      addresses.  <acronym>DNS</acronym> data is maintained in a
      group of distributed
      hierarchical databases.
    </para>

52
    <section xml:id="doc_scope"><info><title>Scope of Document</title></info>
53 54

      <para>
Evan Hunt's avatar
Evan Hunt committed
55 56 57 58 59 60 61
	The Berkeley Internet Name Domain
	(<acronym>BIND</acronym>) implements a
	domain name server for a number of operating systems. This
	document provides basic information about the installation and
	care of the Internet Systems Consortium (<acronym>ISC</acronym>)
	<acronym>BIND</acronym> version 9 software package for
	system administrators.
62
      </para>
Evan Hunt's avatar
Evan Hunt committed
63 64
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkgversion.xml"/>
    </section>
65

66 67
    <section xml:id="organization"><info><title>Organization of This Document</title></info>

68
      <para>
Evan Hunt's avatar
Evan Hunt committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
	In this document, <emphasis>Chapter 1</emphasis> introduces
	the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Chapter 2</emphasis>
	describes resource requirements for running <acronym>BIND</acronym> in various
	environments. Information in <emphasis>Chapter 3</emphasis> is
	<emphasis>task-oriented</emphasis> in its presentation and is
	organized functionally, to aid in the process of installing the
	<acronym>BIND</acronym> 9 software. The task-oriented
	section is followed by
	<emphasis>Chapter 4</emphasis>, which contains more advanced
	concepts that the system administrator may need for implementing
	certain options. <emphasis>Chapter 5</emphasis>
	describes the <acronym>BIND</acronym> 9 lightweight
	resolver.  The contents of <emphasis>Chapter 6</emphasis> are
	organized as in a reference manual to aid in the ongoing
	maintenance of the software. <emphasis>Chapter 7</emphasis> addresses
	security considerations, and
	<emphasis>Chapter 8</emphasis> contains troubleshooting help. The
	main body of the document is followed by several
	<emphasis>appendices</emphasis> which contain useful reference
	information, such as a <emphasis>bibliography</emphasis> and
	historic information related to <acronym>BIND</acronym>
	and the Domain Name
	System.
92
      </para>
Evan Hunt's avatar
Evan Hunt committed
93
    </section>
94
    <section xml:id="conventions"><info><title>Conventions Used in This Document</title></info>
95 96

      <para>
Evan Hunt's avatar
Evan Hunt committed
97 98
	In this document, we use the following general typographic
	conventions:
99 100 101
      </para>

      <informaltable>
Evan Hunt's avatar
Evan Hunt committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
	<tgroup cols="2">
	  <colspec colname="1" colnum="1" colwidth="3.000in"/>
	  <colspec colname="2" colnum="2" colwidth="2.625in"/>
	  <tbody>
	    <row>
	      <entry colname="1">
		<para>
		  <emphasis>To describe:</emphasis>
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  <emphasis>We use the style:</emphasis>
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry colname="1">
		<para>
		  a pathname, filename, URL, hostname,
		  mailing list name, or new term or concept
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  <filename>Fixed width</filename>
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry colname="1">
		<para>
		  literal user
		  input
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  <userinput>Fixed Width Bold</userinput>
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry colname="1">
		<para>
		  program output
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  <computeroutput>Fixed Width</computeroutput>
		</para>
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
158 159 160
      </informaltable>

      <para>
Evan Hunt's avatar
Evan Hunt committed
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
	The following conventions are used in descriptions of the
	<acronym>BIND</acronym> configuration file:<informaltable colsep="0" frame="all" rowsep="0">
		  <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
		      <colspec colname="1" colnum="1" colsep="0" colwidth="3.000in"/>
	    <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/>
	    <tbody>
	      <row rowsep="0">
		<entry colname="1" colsep="1" rowsep="1">
		  <para>
		    <emphasis>To describe:</emphasis>
		  </para>
		</entry>
		<entry colname="2" rowsep="1">
		  <para>
		    <emphasis>We use the style:</emphasis>
		  </para>
		</entry>
	      </row>
	      <row rowsep="0">
		<entry colname="1" colsep="1" rowsep="1">
		  <para>
		    keywords
		  </para>
		</entry>
		<entry colname="2" rowsep="1">
		  <para>
		    <literal>Fixed Width</literal>
		  </para>
		</entry>
	      </row>
	      <row rowsep="0">
		<entry colname="1" colsep="1" rowsep="1">
		  <para>
		    variables
		  </para>
		</entry>
		<entry colname="2" rowsep="1">
		  <para>
		    <varname>Fixed Width</varname>
		  </para>
		</entry>
	      </row>
	      <row rowsep="0">
		<entry colname="1" colsep="1">
		  <para>
		    Optional input
		  </para>
		</entry>
		<entry colname="2">
		  <para>
		    <optional>Text is enclosed in square brackets</optional>
		  </para>
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
218
      </para>
Evan Hunt's avatar
Evan Hunt committed
219
    </section>
220 221
    <section xml:id="dns_overview"><info><title>The Domain Name System (<acronym>DNS</acronym>)</title></info>

222
      <para>
Evan Hunt's avatar
Evan Hunt committed
223 224
	The purpose of this document is to explain the installation
	and upkeep of the <acronym>BIND</acronym> (Berkeley Internet
225
	Name Domain) software package, and we
Evan Hunt's avatar
Evan Hunt committed
226 227
	begin by reviewing the fundamentals of the Domain Name System
	(<acronym>DNS</acronym>) as they relate to <acronym>BIND</acronym>.
228 229
      </para>

230
      <section xml:id="dns_fundamentals"><info><title>DNS Fundamentals</title></info>
Evan Hunt's avatar
Evan Hunt committed
231 232 233 234 235 236 237 238 239 240 241 242 243 244

	<para>
	  The Domain Name System (DNS) is a hierarchical, distributed
	  database.  It stores information for mapping Internet host names to
	  IP
	  addresses and vice versa, mail routing information, and other data
	  used by Internet applications.
	</para>

	<para>
	  Clients look up information in the DNS by calling a
	  <emphasis>resolver</emphasis> library, which sends queries to one or
	  more <emphasis>name servers</emphasis> and interprets the responses.
	  The <acronym>BIND</acronym> 9 software distribution
245 246
	  contains a name server, <command>named</command>, and a set
	  of associated tools.
Evan Hunt's avatar
Evan Hunt committed
247 248
	</para>

249 250
	</section>
	<section xml:id="domain_names"><info><title>Domains and Domain Names</title></info>
Evan Hunt's avatar
Evan Hunt committed
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297

	<para>
	  The data stored in the DNS is identified by <emphasis>domain names</emphasis> that are organized as a tree according to
	  organizational or administrative boundaries. Each node of the tree,
	  called a <emphasis>domain</emphasis>, is given a label. The domain
	  name of the
	  node is the concatenation of all the labels on the path from the
	  node to the <emphasis>root</emphasis> node.  This is represented
	  in written form as a string of labels listed from right to left and
	  separated by dots. A label need only be unique within its parent
	  domain.
	</para>

	<para>
	  For example, a domain name for a host at the
	  company <emphasis>Example, Inc.</emphasis> could be
	  <literal>ourhost.example.com</literal>,
	  where <literal>com</literal> is the
	  top level domain to which
	  <literal>ourhost.example.com</literal> belongs,
	  <literal>example</literal> is
	  a subdomain of <literal>com</literal>, and
	  <literal>ourhost</literal> is the
	  name of the host.
	</para>

	<para>
	  For administrative purposes, the name space is partitioned into
	  areas called <emphasis>zones</emphasis>, each starting at a node and
	  extending down to the leaf nodes or to nodes where other zones
	  start.
	  The data for each zone is stored in a <emphasis>name server</emphasis>, which answers queries about the zone using the
	  <emphasis>DNS protocol</emphasis>.
	</para>

	<para>
	  The data associated with each domain name is stored in the
	  form of <emphasis>resource records</emphasis> (<acronym>RR</acronym>s).
	  Some of the supported resource record types are described in
	  <xref linkend="types_of_resource_records_and_when_to_use_them"/>.
	</para>

	<para>
	  For more detailed information about the design of the DNS and
	  the DNS protocol, please refer to the standards documents listed in
	  <xref linkend="rfcs"/>.
	</para>
Evan Hunt's avatar
Evan Hunt committed
298
      </section>
299

300 301
      <section xml:id="zones"><info><title>Zones</title></info>

Evan Hunt's avatar
Evan Hunt committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
	<para>
	  To properly operate a name server, it is important to understand
	  the difference between a <emphasis>zone</emphasis>
	  and a <emphasis>domain</emphasis>.
	</para>

	<para>
	  As stated previously, a zone is a point of delegation in
	  the <acronym>DNS</acronym> tree. A zone consists of
	  those contiguous parts of the domain
	  tree for which a name server has complete information and over which
	  it has authority. It contains all domain names from a certain point
	  downward in the domain tree except those which are delegated to
	  other zones. A delegation point is marked by one or more
	  <emphasis>NS records</emphasis> in the
	  parent zone, which should be matched by equivalent NS records at
	  the root of the delegated zone.
	</para>

	<para>
	  For instance, consider the <literal>example.com</literal>
	  domain which includes names
	  such as <literal>host.aaa.example.com</literal> and
	  <literal>host.bbb.example.com</literal> even though
	  the <literal>example.com</literal> zone includes
	  only delegations for the <literal>aaa.example.com</literal> and
	  <literal>bbb.example.com</literal> zones.  A zone can
	  map
	  exactly to a single domain, but could also include only part of a
	  domain, the rest of which could be delegated to other
	  name servers. Every name in the <acronym>DNS</acronym>
	  tree is a
	  <emphasis>domain</emphasis>, even if it is
	  <emphasis>terminal</emphasis>, that is, has no
	  <emphasis>subdomains</emphasis>.  Every subdomain is a domain and
	  every domain except the root is also a subdomain. The terminology is
	  not intuitive and we suggest that you read RFCs 1033, 1034 and 1035
	  to
	  gain a complete understanding of this difficult and subtle
	  topic.
	</para>

	<para>
	  Though <acronym>BIND</acronym> is called a "domain name
	  server",
	  it deals primarily in terms of zones. The master and slave
	  declarations in the <filename>named.conf</filename> file
	  specify
	  zones, not domains. When you ask some other site if it is willing to
	  be a slave server for your <emphasis>domain</emphasis>, you are
	  actually asking for slave service for some collection of zones.
	</para>
Evan Hunt's avatar
Evan Hunt committed
354
      </section>
355

356
      <section xml:id="auth_servers"><info><title>Authoritative Name Servers</title></info>
Evan Hunt's avatar
Evan Hunt committed
357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373

	<para>
	  Each zone is served by at least
	  one <emphasis>authoritative name server</emphasis>,
	  which contains the complete data for the zone.
	  To make the DNS tolerant of server and network failures,
	  most zones have two or more authoritative servers, on
	  different networks.
	</para>

	<para>
	  Responses from authoritative servers have the "authoritative
	  answer" (AA) bit set in the response packets.  This makes them
	  easy to identify when debugging DNS configurations using tools like
	  <command>dig</command> (<xref linkend="diagnostic_tools"/>).
	</para>

374
	<section xml:id="primary_master"><info><title>The Primary Master</title></info>
Evan Hunt's avatar
Evan Hunt committed
375 376 377 378

	  <para>
	    The authoritative server where the master copy of the zone
	    data is maintained is called the
379
	    <emphasis>primary master</emphasis> server, or simply the
Evan Hunt's avatar
Evan Hunt committed
380 381 382 383
	    <emphasis>primary</emphasis>.  Typically it loads the zone
	    contents from some local file edited by humans or perhaps
	    generated mechanically from some other local file which is
	    edited by humans.  This file is called the
384 385
	    <emphasis>zone file</emphasis> or
	    <emphasis>master file</emphasis>.
Evan Hunt's avatar
Evan Hunt committed
386
	  </para>
387 388 389 390 391 392

	  <para>
	    In some cases, however, the master file may not be edited
	    by humans at all, but may instead be the result of
	    <emphasis>dynamic update</emphasis> operations.
	  </para>
Evan Hunt's avatar
Evan Hunt committed
393
	</section>
Evan Hunt's avatar
Evan Hunt committed
394

395 396
	<section xml:id="slave_server"><info><title>Slave Servers</title></info>

Evan Hunt's avatar
Evan Hunt committed
397 398 399 400 401 402 403 404 405 406 407 408
	  <para>
	    The other authoritative servers, the <emphasis>slave</emphasis>
	    servers (also known as <emphasis>secondary</emphasis> servers)
	    load
	    the zone contents from another server using a replication process
	    known as a <emphasis>zone transfer</emphasis>.  Typically the data
	    are
	    transferred directly from the primary master, but it is also
	    possible
	    to transfer it from another slave.  In other words, a slave server
	    may itself act as a master to a subordinate slave server.
	  </para>
Evan Hunt's avatar
Evan Hunt committed
409
	</section>
Evan Hunt's avatar
Evan Hunt committed
410

411
	<section xml:id="stealth_server"><info><title>Stealth Servers</title></info>
Evan Hunt's avatar
Evan Hunt committed
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445

	  <para>
	    Usually all of the zone's authoritative servers are listed in
	    NS records in the parent zone.  These NS records constitute
	    a <emphasis>delegation</emphasis> of the zone from the parent.
	    The authoritative servers are also listed in the zone file itself,
	    at the <emphasis>top level</emphasis> or <emphasis>apex</emphasis>
	    of the zone.  You can list servers in the zone's top-level NS
	    records that are not in the parent's NS delegation, but you cannot
	    list servers in the parent's delegation that are not present at
	    the zone's top level.
	  </para>

	  <para>
	    A <emphasis>stealth server</emphasis> is a server that is
	    authoritative for a zone but is not listed in that zone's NS
	    records.  Stealth servers can be used for keeping a local copy of
	    a
	    zone to speed up access to the zone's records or to make sure that
	    the
	    zone is available even if all the "official" servers for the zone
	    are
	    inaccessible.
	  </para>

	  <para>
	    A configuration where the primary master server itself is a
	    stealth server is often referred to as a "hidden primary"
	    configuration.  One use for this configuration is when the primary
	    master
	    is behind a firewall and therefore unable to communicate directly
	    with the outside world.
	  </para>

Evan Hunt's avatar
Evan Hunt committed
446
	</section>
447

Evan Hunt's avatar
Evan Hunt committed
448
      </section>
449
      <section xml:id="cache_servers"><info><title>Caching Name Servers</title></info>
450

451
	<!--
452
	  - Terminology here is inconsistent.  Probably ought to
453 454 455 456
	  - convert to using "recursive name server" everywhere
	  - with just a note about "caching" terminology.
	  -->

Evan Hunt's avatar
Evan Hunt committed
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
	<para>
	  The resolver libraries provided by most operating systems are
	  <emphasis>stub resolvers</emphasis>, meaning that they are not
	  capable of
	  performing the full DNS resolution process by themselves by talking
	  directly to the authoritative servers.  Instead, they rely on a
	  local
	  name server to perform the resolution on their behalf.  Such a
	  server
	  is called a <emphasis>recursive</emphasis> name server; it performs
	  <emphasis>recursive lookups</emphasis> for local clients.
	</para>

	<para>
	  To improve performance, recursive servers cache the results of
	  the lookups they perform.  Since the processes of recursion and
	  caching are intimately connected, the terms
	  <emphasis>recursive server</emphasis> and
	  <emphasis>caching server</emphasis> are often used synonymously.
	</para>

	<para>
	  The length of time for which a record may be retained in
	  the cache of a caching name server is controlled by the
	  Time To Live (TTL) field associated with each resource record.
	</para>

484
	<section xml:id="forwarder"><info><title>Forwarding</title></info>
Evan Hunt's avatar
Evan Hunt committed
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508

	  <para>
	    Even a caching name server does not necessarily perform
	    the complete recursive lookup itself.  Instead, it can
	    <emphasis>forward</emphasis> some or all of the queries
	    that it cannot satisfy from its cache to another caching name
	    server,
	    commonly referred to as a <emphasis>forwarder</emphasis>.
	  </para>

	  <para>
	    There may be one or more forwarders,
	    and they are queried in turn until the list is exhausted or an
	    answer
	    is found. Forwarders are typically used when you do not
	    wish all the servers at a given site to interact directly with the
	    rest of
	    the Internet servers. A typical scenario would involve a number
	    of internal <acronym>DNS</acronym> servers and an
	    Internet firewall. Servers unable
	    to pass packets through the firewall would forward to the server
	    that can do it, and that server would query the Internet <acronym>DNS</acronym> servers
	    on the internal server's behalf.
	  </para>
Evan Hunt's avatar
Evan Hunt committed
509
	</section>
510

Evan Hunt's avatar
Evan Hunt committed
511
      </section>
512

513
      <section xml:id="multi_role"><info><title>Name Servers in Multiple Roles</title></info>
Evan Hunt's avatar
Evan Hunt committed
514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536

	<para>
	  The <acronym>BIND</acronym> name server can
	  simultaneously act as
	  a master for some zones, a slave for other zones, and as a caching
	  (recursive) server for a set of local clients.
	</para>

	<para>
	  However, since the functions of authoritative name service
	  and caching/recursive name service are logically separate, it is
	  often advantageous to run them on separate server machines.

	  A server that only provides authoritative name service
	  (an <emphasis>authoritative-only</emphasis> server) can run with
	  recursion disabled, improving reliability and security.

	  A server that is not authoritative for any zones and only provides
	  recursive service to local
	  clients (a <emphasis>caching-only</emphasis> server)
	  does not need to be reachable from the Internet at large and can
	  be placed inside a firewall.
	</para>
537

Evan Hunt's avatar
Evan Hunt committed
538 539
      </section>
    </section>
540 541 542

  </chapter>

Evan Hunt's avatar
Evan Hunt committed
543
  <chapter xml:id="Bv9ARM.ch02"><info><title><acronym>BIND</acronym> Resource Requirements</title></info>
544

545
    <section xml:id="hw_req"><info><title>Hardware requirements</title></info>
546
      <para>
Evan Hunt's avatar
Evan Hunt committed
547 548 549 550
	<acronym>DNS</acronym> hardware requirements have
	traditionally been quite modest.
	For many installations, servers that have been pensioned off from
	active duty have performed admirably as <acronym>DNS</acronym> servers.
551 552
      </para>
      <para>
Evan Hunt's avatar
Evan Hunt committed
553 554 555 556 557 558 559
	The DNSSEC features of <acronym>BIND</acronym> 9
	may prove to be quite
	CPU intensive however, so organizations that make heavy use of these
	features may wish to consider larger systems for these applications.
	<acronym>BIND</acronym> 9 is fully multithreaded, allowing
	full utilization of
	multiprocessor systems for installations that need it.
560
      </para>
Evan Hunt's avatar
Evan Hunt committed
561
    </section>
562
    <section xml:id="cpu_req"><info><title>CPU Requirements</title></info>
563
      <para>
Evan Hunt's avatar
Evan Hunt committed
564 565 566 567 568
	CPU requirements for <acronym>BIND</acronym> 9 range from
	i486-class machines
	for serving of static zones without caching, to enterprise-class
	machines if you intend to process many dynamic updates and DNSSEC
	signed zones, serving many thousands of queries per second.
569
      </para>
Evan Hunt's avatar
Evan Hunt committed
570
    </section>
571
    <section xml:id="mem_req"><info><title>Memory Requirements</title></info>
572
      <para>
Evan Hunt's avatar
Evan Hunt committed
573 574 575 576 577 578
	The memory of the server has to be large enough to fit the
	cache and zones loaded off disk.  The <command>max-cache-size</command>
	option can be used to limit the amount of memory used by the cache,
	at the expense of reducing cache hit rates and causing more <acronym>DNS</acronym>
	traffic.
	It is still good practice to have enough memory to load
Evan Hunt's avatar
Evan Hunt committed
579
	all zone and cache data into memory — unfortunately, the best
Evan Hunt's avatar
Evan Hunt committed
580 581 582 583 584
	way
	to determine this for a given installation is to watch the name server
	in operation. After a few weeks the server process should reach
	a relatively stable size where entries are expiring from the cache as
	fast as they are being inserted.
585
      </para>
586
      <!--
Evan Hunt's avatar
Evan Hunt committed
587
	- Add something here about leaving overhead for attacks?
588
	- How much overhead?  Percentage?
Evan Hunt's avatar
Evan Hunt committed
589
	-->
Evan Hunt's avatar
Evan Hunt committed
590
    </section>
591

592 593
    <section xml:id="intensive_env"><info><title>Name Server Intensive Environment Issues</title></info>

594
      <para>
Evan Hunt's avatar
Evan Hunt committed
595 596 597 598 599 600 601 602 603 604 605
	For name server intensive environments, there are two alternative
	configurations that may be used. The first is where clients and
	any second-level internal name servers query a main name server, which
	has enough memory to build a large cache. This approach minimizes
	the bandwidth used by external name lookups. The second alternative
	is to set up second-level internal name servers to make queries
	independently.
	In this configuration, none of the individual machines needs to
	have as much memory or CPU power as in the first alternative, but
	this has the disadvantage of making many more external queries,
	as none of the name servers share their cached data.
606
      </para>
Evan Hunt's avatar
Evan Hunt committed
607
    </section>
608

609 610
    <section xml:id="supported_os"><info><title>Supported Operating Systems</title></info>

611
      <para>
Evan Hunt's avatar
Evan Hunt committed
612 613
	ISC <acronym>BIND</acronym> 9 compiles and runs on a large
	number
Mark Andrews's avatar
Mark Andrews committed
614
	of Unix-like operating systems and on
Evan Hunt's avatar
Evan Hunt committed
615 616 617 618 619
	Microsoft Windows Server 2003 and 2008, and Windows XP and Vista.
	For an up-to-date
	list of supported systems, see the README file in the top level
	directory
	of the BIND 9 source distribution.
620
      </para>
Evan Hunt's avatar
Evan Hunt committed
621
    </section>
622 623
  </chapter>

Evan Hunt's avatar
Evan Hunt committed
624
  <chapter xml:id="Bv9ARM.ch03"><info><title>Name Server Configuration</title></info>
625

626
    <para>
627
      In this chapter we provide some suggested configurations along
628 629
      with guidelines for their use.  We suggest reasonable values for
      certain option settings.
630 631
    </para>

Evan Hunt's avatar
Evan Hunt committed
632
    <section xml:id="sample_configuration"><info><title>Sample Configurations</title></info>
633 634 635

      <section xml:id="cache_only_sample"><info><title>A Caching-only Name Server</title></info>

Evan Hunt's avatar
Evan Hunt committed
636 637 638 639 640 641 642 643 644
	<para>
	  The following sample configuration is appropriate for a caching-only
	  name server for use by clients internal to a corporation.  All
	  queries
	  from outside clients are refused using the <command>allow-query</command>
	  option.  Alternatively, the same effect could be achieved using
	  suitable
	  firewall rules.
	</para>
645 646

<programlisting>
647
// Two corporate subnets we wish to allow queries from.
648
acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
649
options {
650 651 652
     // Working directory
     directory "/etc/namedb";

653
     allow-query { corpnets; };
654
};
655 656
// Provide a reverse mapping for the loopback
// address 127.0.0.1
657 658 659 660 661 662
zone "0.0.127.in-addr.arpa" {
     type master;
     file "localhost.rev";
     notify no;
};
</programlisting>
663

Evan Hunt's avatar
Evan Hunt committed
664
      </section>
665

666 667
      <section xml:id="auth_only_sample"><info><title>An Authoritative-only Name Server</title></info>

Evan Hunt's avatar
Evan Hunt committed
668 669 670 671 672
	<para>
	  This sample configuration is for an authoritative-only server
	  that is the master server for "<filename>example.com</filename>"
	  and a slave for the subdomain "<filename>eng.example.com</filename>".
	</para>
673 674

<programlisting>
675
options {
676 677 678 679 680 681 682 683
     // Working directory
     directory "/etc/namedb";
     // Do not allow access to cache
     allow-query-cache { none; };
     // This is the default
     allow-query { any; };
     // Do not provide recursive service
     recursion no;
684 685
};

686 687
// Provide a reverse mapping for the loopback
// address 127.0.0.1
688 689 690 691 692 693 694 695 696
zone "0.0.127.in-addr.arpa" {
     type master;
     file "localhost.rev";
     notify no;
};
// We are the master server for example.com
zone "example.com" {
     type master;
     file "example.com.db";
697 698
     // IP addresses of slave servers allowed to
     // transfer example.com
699
     allow-transfer {
Evan Hunt's avatar
Evan Hunt committed
700 701
	  192.168.4.14;
	  192.168.5.53;
702 703 704 705 706 707 708 709 710 711
     };
};
// We are a slave server for eng.example.com
zone "eng.example.com" {
     type slave;
     file "eng.example.com.bk";
     // IP address of eng.example.com master server
     masters { 192.168.4.12; };
};
</programlisting>
712

Evan Hunt's avatar
Evan Hunt committed
713 714
      </section>
    </section>
715

716 717
    <section xml:id="load_balancing"><info><title>Load Balancing</title></info>

718
      <!--
Evan Hunt's avatar
Evan Hunt committed
719
	- Add explanation of why load balancing is fragile at best
720
	- and completely pointless in the general case.
Evan Hunt's avatar
Evan Hunt committed
721
	-->
722 723

      <para>
Evan Hunt's avatar
Evan Hunt committed
724 725
	A primitive form of load balancing can be achieved in
	the <acronym>DNS</acronym> by using multiple records
726
	(such as multiple A records) for one name.
727 728 729
      </para>

      <para>
Evan Hunt's avatar
Evan Hunt committed
730 731 732 733
	For example, if you have three WWW servers with network addresses
	of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the
	following means that clients will connect to each machine one third
	of the time:
734 735 736
      </para>

      <informaltable colsep="0" rowsep="0">
Evan Hunt's avatar
Evan Hunt committed
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849
	<tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="2Level-table">
	  <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/>
	  <colspec colname="2" colnum="2" colsep="0" colwidth="0.500in"/>
	  <colspec colname="3" colnum="3" colsep="0" colwidth="0.750in"/>
	  <colspec colname="4" colnum="4" colsep="0" colwidth="0.750in"/>
	  <colspec colname="5" colnum="5" colsep="0" colwidth="2.028in"/>
	  <tbody>
	    <row rowsep="0">
	      <entry colname="1">
		<para>
		  Name
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  TTL
		</para>
	      </entry>
	      <entry colname="3">
		<para>
		  CLASS
		</para>
	      </entry>
	      <entry colname="4">
		<para>
		  TYPE
		</para>
	      </entry>
	      <entry colname="5">
		<para>
		  Resource Record (RR) Data
		</para>
	      </entry>
	    </row>
	    <row rowsep="0">
	      <entry colname="1">
		<para>
		  <literal>www</literal>
		</para>
	      </entry>
	      <entry colname="2">
		<para>
		  <literal>600</literal>
		</para>
	      </entry>
	      <entry colname="3">
		<para>
		  <literal>IN</literal>
		</para>
	      </entry>
	      <entry colname="4">
		<para>
		  <literal>A</literal>
		</para>
	      </entry>
	      <entry colname="5">
		<para>
		  <literal>10.0.0.1</literal>
		</para>
	      </entry>
	    </row>
	    <row rowsep="0">
	      <entry colname="1">
		<para/>
	      </entry>
	      <entry colname="2">
		<para>
		  <literal>600</literal>
		</para>
	      </entry>
	      <entry colname="3">
		<para>
		  <literal>IN</literal>
		</para>
	      </entry>
	      <entry colname="4">
		<para>
		  <literal>A</literal>
		</para>
	      </entry>
	      <entry colname="5">
		<para>
		  <literal>10.0.0.2</literal>
		</para>
	      </entry>
	    </row>
	    <row rowsep="0">
	      <entry colname="1">
		<para/>
	      </entry>
	      <entry colname="2">
		<para>
		  <literal>600</literal>
		</para>
	      </entry>
	      <entry colname="3">
		<para>
		  <literal>IN</literal>
		</para>
	      </entry>
	      <entry colname="4">
		<para>
		  <literal>A</literal>
		</para>
	      </entry>
	      <entry colname="5">
		<para>
		  <literal>10.0.0.3</literal>
		</para>
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
850 851
      </informaltable>
      <para>
Evan Hunt's avatar
Evan Hunt committed
852 853 854 855 856
	When a resolver queries for these records, <acronym>BIND</acronym> will rotate
	them and respond to the query with the records in a different
	order.  In the example above, clients will randomly receive
	records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients
	will use the first record returned and discard the rest.
857 858
      </para>
      <para>
Evan Hunt's avatar
Evan Hunt committed
859 860 861 862
	For more detail on ordering responses, check the
	<command>rrset-order</command> sub-statement in the
	<command>options</command> statement, see
	<xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>.
863 864
      </para>

Evan Hunt's avatar
Evan Hunt committed
865
    </section>
866

867
    <section xml:id="ns_operations"><info><title>Name Server Operations</title></info>
868

869
      <section xml:id="tools"><info><title>Tools for Use With the Name Server Daemon</title></info>
Evan Hunt's avatar
Evan Hunt committed
870 871 872 873 874 875
	<para>
	  This section describes several indispensable diagnostic,
	  administrative and monitoring tools available to the system
	  administrator for controlling and debugging the name server
	  daemon.
	</para>
Evan Hunt's avatar
Evan Hunt committed
876
	<section xml:id="diagnostic_tools"><info><title>Diagnostic Tools</title></info>
Evan Hunt's avatar
Evan Hunt committed
877 878 879 880 881 882 883 884 885 886
	  <para>
	    The <command>dig</command>, <command>host</command>, and
	    <command>nslookup</command> programs are all command
	    line tools
	    for manually querying name servers.  They differ in style and
	    output format.
	  </para>

	  <variablelist>
	    <varlistentry>
Evan Hunt's avatar
Evan Hunt committed
887
	      <term xml:id="dig"><command>dig</command></term>
Evan Hunt's avatar
Evan Hunt committed
888 889
	      <listitem>
		<para>
890
		  <command>dig</command>
Evan Hunt's avatar
Evan Hunt committed
891 892 893 894 895 896 897 898
		  is the most versatile and complete of these lookup tools.
		  It has two modes: simple interactive
		  mode for a single query, and batch mode which executes a
		  query for
		  each in a list of several query lines. All query options are
		  accessible
		  from the command line.
		</para>
Evan Hunt's avatar
Evan Hunt committed
899
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
900
		  <command>dig</command>
Evan Hunt's avatar
Evan Hunt committed
901 902 903 904 905 906 907
		  <arg choice="opt" rep="norepeat">@<replaceable>server</replaceable></arg>
		  <arg choice="plain" rep="norepeat"><replaceable>domain</replaceable></arg>
		  <arg choice="opt" rep="norepeat"><replaceable>query-type</replaceable></arg>
		  <arg choice="opt" rep="norepeat"><replaceable>query-class</replaceable></arg>
		  <arg choice="opt" rep="norepeat">+<replaceable>query-option</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-<replaceable>dig-option</replaceable></arg>
		  <arg choice="opt" rep="norepeat">%<replaceable>comment</replaceable></arg>
Evan Hunt's avatar
Evan Hunt committed
908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933
		</cmdsynopsis>
		<para>
		  The usual simple use of <command>dig</command> will take the form
		</para>
		<simpara>
		  <command>dig @server domain query-type query-class</command>
		</simpara>
		<para>
		  For more information and a list of available commands and
		  options, see the <command>dig</command> man
		  page.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><command>host</command></term>
	      <listitem>
		<para>
		  The <command>host</command> utility emphasizes
		  simplicity
		  and ease of use.  By default, it converts
		  between host names and Internet addresses, but its
		  functionality
		  can be extended with the use of options.
		</para>
Evan Hunt's avatar
Evan Hunt committed
934
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
935
		  <command>host</command>
Evan Hunt's avatar
Evan Hunt committed
936 937 938 939 940 941 942 943 944 945 946
		  <arg choice="opt" rep="norepeat">-aCdlnrsTwv</arg>
		  <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-N <replaceable>ndots</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-t <replaceable>type</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-W <replaceable>timeout</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-R <replaceable>retries</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-m <replaceable>flag</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-4</arg>
		  <arg choice="opt" rep="norepeat">-6</arg>
		  <arg choice="plain" rep="norepeat"><replaceable>hostname</replaceable></arg>
		  <arg choice="opt" rep="norepeat"><replaceable>server</replaceable></arg>
Evan Hunt's avatar
Evan Hunt committed
947 948 949 950 951 952 953 954 955 956 957
		</cmdsynopsis>
		<para>
		  For more information and a list of available commands and
		  options, see the <command>host</command> man
		  page.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><command>nslookup</command></term>
958
	      <listitem>
Evan Hunt's avatar
Evan Hunt committed
959 960 961 962 963 964 965 966 967
		<para><command>nslookup</command>
		  has two modes: interactive and
		  non-interactive. Interactive mode allows the user to
		  query name servers for information about various
		  hosts and domains or to print a list of hosts in a
		  domain. Non-interactive mode is used to print just
		  the name and requested information for a host or
		  domain.
		</para>
Evan Hunt's avatar
Evan Hunt committed
968
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
969
		  <command>nslookup</command>
Evan Hunt's avatar
Evan Hunt committed
970 971 972 973
		  <arg rep="repeat" choice="opt">-option</arg>
		  <group choice="opt" rep="norepeat">
		    <arg choice="opt" rep="norepeat"><replaceable>host-to-find</replaceable></arg>
		    <arg choice="opt" rep="norepeat">- <arg choice="opt" rep="norepeat">server</arg></arg>
Evan Hunt's avatar
Evan Hunt committed
974 975
		  </group>
		</cmdsynopsis>
976
		<para>
Evan Hunt's avatar
Evan Hunt committed
977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995
		  Interactive mode is entered when no arguments are given (the
		  default name server will be used) or when the first argument
		  is a
		  hyphen (`-') and the second argument is the host name or
		  Internet address
		  of a name server.
		</para>
		<para>
		  Non-interactive mode is used when the name or Internet
		  address
		  of the host to be looked up is given as the first argument.
		  The
		  optional second argument specifies the host name or address
		  of a name server.
		</para>
		<para>
		  Due to its arcane user interface and frequently inconsistent
		  behavior, we do not recommend the use of <command>nslookup</command>.
		  Use <command>dig</command> instead.
996
		</para>
Mark Andrews's avatar
Mark Andrews committed
997
	      </listitem>
Evan Hunt's avatar
Evan Hunt committed
998

999
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1000
	  </variablelist>
Evan Hunt's avatar
Evan Hunt committed
1001
	</section>
1002

Evan Hunt's avatar
Evan Hunt committed
1003
	<section xml:id="admin_tools"><info><title>Administrative Tools</title></info>
Evan Hunt's avatar
Evan Hunt committed
1004 1005 1006 1007 1008
	  <para>
	    Administrative tools play an integral part in the management
	    of a server.
	  </para>
	  <variablelist>
Evan Hunt's avatar
Evan Hunt committed
1009
	    <varlistentry xml:id="named-checkconf" xreflabel="Named Configuration Checking application">
Evan Hunt's avatar
Evan Hunt committed
1010 1011 1012 1013 1014 1015 1016

	      <term><command>named-checkconf</command></term>
	      <listitem>
		<para>
		  The <command>named-checkconf</command> program
		  checks the syntax of a <filename>named.conf</filename> file.
		</para>
Evan Hunt's avatar
Evan Hunt committed
1017
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1018
		  <command>named-checkconf</command>
Evan Hunt's avatar
Evan Hunt committed
1019 1020 1021
		  <arg choice="opt" rep="norepeat">-jvz</arg>
		  <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg>
		  <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg>
Evan Hunt's avatar
Evan Hunt committed
1022 1023 1024
		</cmdsynopsis>
	      </listitem>
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1025
	    <varlistentry xml:id="named-checkzone" xreflabel="Zone Checking application">
Evan Hunt's avatar
Evan Hunt committed
1026 1027 1028 1029 1030 1031 1032 1033

	      <term><command>named-checkzone</command></term>
	      <listitem>
		<para>
		  The <command>named-checkzone</command> program
		  checks a master file for
		  syntax and consistency.
		</para>
Evan Hunt's avatar
Evan Hunt committed
1034
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1035
		  <command>named-checkzone</command>
Evan Hunt's avatar
Evan Hunt committed
1036 1037 1038 1039 1040 1041 1042 1043 1044 1045
		  <arg choice="opt" rep="norepeat">-djqvD</arg>
		  <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-o <replaceable>output</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-w <replaceable>directory</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-k <replaceable>(ignore|warn|fail)</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-n <replaceable>(ignore|warn|fail)</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-W <replaceable>(ignore|warn)</replaceable></arg>
		  <arg choice="plain" rep="norepeat"><replaceable>zone</replaceable></arg>
		  <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg>
Evan Hunt's avatar
Evan Hunt committed
1046 1047 1048
		</cmdsynopsis>
	      </listitem>
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1049
	    <varlistentry xml:id="named-compilezone" xreflabel="Zone Compilation application">
Evan Hunt's avatar
Evan Hunt committed
1050 1051 1052 1053 1054 1055 1056 1057 1058
	      <term><command>named-compilezone</command></term>
	      <listitem>
		<para>
		  Similar to <command>named-checkzone,</command> but
		  it always dumps the zone content to a specified file
		  (typically in a different format).
		</para>
	      </listitem>
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1059
	    <varlistentry xml:id="rndc" xreflabel="Remote Name Daemon Control application">
Evan Hunt's avatar
Evan Hunt committed
1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077

	      <term><command>rndc</command></term>
	      <listitem>
		<para>
		  The remote name daemon control
		  (<command>rndc</command>) program allows the
		  system
		  administrator to control the operation of a name server.
		  Since <acronym>BIND</acronym> 9.2, <command>rndc</command>
		  supports all the commands of the BIND 8 <command>ndc</command>
		  utility except <command>ndc start</command> and
		  <command>ndc restart</command>, which were also
		  not supported in <command>ndc</command>'s
		  channel mode.
		  If you run <command>rndc</command> without any
		  options
		  it will display a usage message as follows:
		</para>
Evan Hunt's avatar
Evan Hunt committed
1078
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1079
		  <command>rndc</command>
Evan Hunt's avatar
Evan Hunt committed
1080 1081 1082 1083 1084 1085
		  <arg choice="opt" rep="norepeat">-c <replaceable>config</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-s <replaceable>server</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-p <replaceable>port</replaceable></arg>
		  <arg choice="opt" rep="norepeat">-y <replaceable>key</replaceable></arg>
		  <arg choice="plain" rep="norepeat"><replaceable>command</replaceable></arg>
		  <arg rep="repeat" choice="opt"><replaceable>command</replaceable></arg>
Evan Hunt's avatar
Evan Hunt committed
1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199
		</cmdsynopsis>

		<para>See <xref linkend="man.rndc"/> for details of
		  the available <command>rndc</command> commands.
		</para>

		<para>
		  <command>rndc</command> requires a configuration file,
		  since all
		  communication with the server is authenticated with
		  digital signatures that rely on a shared secret, and
		  there is no way to provide that secret other than with a
		  configuration file.  The default location for the
		  <command>rndc</command> configuration file is
		  <filename>/etc/rndc.conf</filename>, but an
		  alternate
		  location can be specified with the <option>-c</option>
		  option.  If the configuration file is not found,
		  <command>rndc</command> will also look in
		  <filename>/etc/rndc.key</filename> (or whatever
		  <varname>sysconfdir</varname> was defined when
		  the <acronym>BIND</acronym> build was
		  configured).
		  The <filename>rndc.key</filename> file is
		  generated by
		  running <command>rndc-confgen -a</command> as
		  described in
		  <xref linkend="controls_statement_definition_and_usage"/>.
		</para>

		<para>
		  The format of the configuration file is similar to
		  that of <filename>named.conf</filename>, but
		  limited to
		  only four statements, the <command>options</command>,
		  <command>key</command>, <command>server</command> and
		  <command>include</command>
		  statements.  These statements are what associate the
		  secret keys to the servers with which they are meant to
		  be shared.  The order of statements is not
		  significant.
		</para>

		<para>
		  The <command>options</command> statement has
		  three clauses:
		  <command>default-server</command>, <command>default-key</command>,
		  and <command>default-port</command>.
		  <command>default-server</command> takes a
		  host name or address argument  and represents the server
		  that will
		  be contacted if no <option>-s</option>
		  option is provided on the command line.
		  <command>default-key</command> takes
		  the name of a key as its argument, as defined by a <command>key</command> statement.
		  <command>default-port</command> specifies the
		  port to which
		  <command>rndc</command> should connect if no
		  port is given on the command line or in a
		  <command>server</command> statement.
		</para>

		<para>
		  The <command>key</command> statement defines a
		  key to be used
		  by <command>rndc</command> when authenticating
		  with
		  <command>named</command>.  Its syntax is
		  identical to the
		  <command>key</command> statement in <filename>named.conf</filename>.
		  The keyword <userinput>key</userinput> is
		  followed by a key name, which must be a valid
		  domain name, though it need not actually be hierarchical;
		  thus,
		  a string like "<userinput>rndc_key</userinput>" is a valid
		  name.
		  The <command>key</command> statement has two
		  clauses:
		  <command>algorithm</command> and <command>secret</command>.
		  While the configuration parser will accept any string as the
		  argument
		  to algorithm, currently only the strings
		  "<userinput>hmac-md5</userinput>",
		  "<userinput>hmac-sha1</userinput>",
		  "<userinput>hmac-sha224</userinput>",
		  "<userinput>hmac-sha256</userinput>",
		  "<userinput>hmac-sha384</userinput>"
		  and "<userinput>hmac-sha512</userinput>"
		  have any meaning.  The secret is a base-64 encoded string
		  as specified in RFC 3548.
		</para>

		<para>
		  The <command>server</command> statement
		  associates a key
		  defined using the <command>key</command>
		  statement with a server.
		  The keyword <userinput>server</userinput> is followed by a
		  host name or address.  The <command>server</command> statement
		  has two clauses: <command>key</command> and <command>port</command>.
		  The <command>key</command> clause specifies the
		  name of the key
		  to be used when communicating with this server, and the
		  <command>port</command> clause can be used to
		  specify the port <command>rndc</command> should
		  connect
		  to on the server.
		</para>

		<para>
		  A sample minimal configuration file is as follows:
		</para>

<programlisting>
1200
key rndc_key {
1201
     algorithm "hmac-sha256";
1202 1203
     secret
       "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
1204 1205
};
options {
1206
     default-server 127.0.0.1;
1207 1208 1209
     default-key    rndc_key;
};
</programlisting>
1210

Evan Hunt's avatar
Evan Hunt committed
1211 1212 1213 1214
		<para>
		  This file, if installed as <filename>/etc/rndc.conf</filename>,
		  would allow the command:
		</para>
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1215

Evan Hunt's avatar
Evan Hunt committed
1216 1217 1218
		<para>
		  <prompt>$ </prompt><userinput>rndc reload</userinput>
		</para>
1219

Evan Hunt's avatar
Evan Hunt committed
1220 1221 1222 1223 1224 1225
		<para>
		  to connect to 127.0.0.1 port 953 and cause the name server
		  to reload, if a name server on the local machine were
		  running with
		  following controls statements:
		</para>
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1226 1227

<programlisting>
1228
controls {
Evan Hunt's avatar
Evan Hunt committed
1229 1230
	inet 127.0.0.1
	    allow { localhost; } keys { rndc_key; };
1231 1232 1233
};
</programlisting>

Evan Hunt's avatar
Evan Hunt committed
1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258
		<para>
		  and it had an identical key statement for
		  <literal>rndc_key</literal>.
		</para>

		<para>
		  Running the <command>rndc-confgen</command>
		  program will
		  conveniently create a <filename>rndc.conf</filename>
		  file for you, and also display the
		  corresponding <command>controls</command>
		  statement that you need to
		  add to <filename>named.conf</filename>.
		  Alternatively,
		  you can run <command>rndc-confgen -a</command>
		  to set up
		  a <filename>rndc.key</filename> file and not
		  modify
		  <filename>named.conf</filename> at all.
		</para>

	      </listitem>
	    </varlistentry>
	  </variablelist>

Evan Hunt's avatar
Evan Hunt committed
1259 1260
	</section>
      </section>
1261

1262
      <section xml:id="signals"><info><title>Signals</title></info>
Evan Hunt's avatar
Evan Hunt committed
1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306
	<para>
	  Certain UNIX signals cause the name server to take specific
	  actions, as described in the following table.  These signals can
	  be sent using the <command>kill</command> command.
	</para>
	<informaltable frame="all">
	  <tgroup cols="2">
	    <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/>
	    <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/>
	    <tbody>
	      <row rowsep="0">
		<entry colname="1">
		  <para><command>SIGHUP</command></para>
		</entry>
		<entry colname="2">
		  <para>
		    Causes the server to read <filename>named.conf</filename> and
		    reload the database.
		  </para>
		</entry>
	      </row>
	      <row rowsep="0">
		<entry colname="1">
		  <para><command>SIGTERM</command></para>
		</entry>
		<entry colname="2">
		  <para>
		    Causes the server to clean up and exit.
		  </para>
		</entry>
	      </row>
	      <row rowsep="0">
		<entry colname="1">
		  <para><command>SIGINT</command></para>
		</entry>
		<entry colname="2">
		  <para>
		    Causes the server to clean up and exit.
		  </para>
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>
Evan Hunt's avatar
Evan Hunt committed
1307 1308
      </section>
    </section>
1309 1310
  </chapter>

Evan Hunt's avatar
Evan Hunt committed
1311
  <chapter xml:id="Bv9ARM.ch04"><info><title>Advanced DNS Features</title></info>
1312

Evan Hunt's avatar
Evan Hunt committed
1313
    <section xml:id="notify"><info><title>Notify</title></info>
1314
      <para>
Evan Hunt's avatar
Evan Hunt committed
1315 1316 1317 1318 1319
	<acronym>DNS</acronym> NOTIFY is a mechanism that allows master
	servers to notify their slave servers of changes to a zone's data. In
	response to a <command>NOTIFY</command> from a master server, the
	slave will check to see that its version of the zone is the
	current version and, if not, initiate a zone transfer.
1320 1321 1322
      </para>

      <para>
Evan Hunt's avatar
Evan Hunt committed
1323 1324 1325 1326 1327 1328
	For more information about <acronym>DNS</acronym>
	<command>NOTIFY</command>, see the description of the
	<command>notify</command> option in <xref linkend="boolean_options"/> and
	the description of the zone option <command>also-notify</command> in
	<xref linkend="zone_transfers"/>.  The <command>NOTIFY</command>
	protocol is specified in RFC 1996.
1329 1330
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1331
      <note><simpara>
1332
	As a slave zone can also be a master to other slaves, <command>named</command>,
Evan Hunt's avatar
Evan Hunt committed
1333
	by default, sends <command>NOTIFY</command> messages for every zone
1334
	it loads.  Specifying <command>notify master-only;</command> will
1335
	cause <command>named</command> to only send <command>NOTIFY</command> for master
1336
	zones that it loads.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1337
      </simpara></note>
1338

Evan Hunt's avatar
Evan Hunt committed
1339
    </section>
1340

Evan Hunt's avatar
Evan Hunt committed
1341
    <section xml:id="dynamic_update"><info><title>Dynamic Update</title></info>
1342 1343

      <para>
Evan Hunt's avatar
Evan Hunt committed
1344 1345 1346 1347
	Dynamic Update is a method for adding, replacing or deleting
	records in a master server by sending it a special form of DNS
	messages.  The format and meaning of these messages is specified
	in RFC 2136.
1348 1349 1350
      </para>

      <para>
1351
	Dynamic update is enabled by including an
1352 1353
	<command>allow-update</command> or an <command>update-policy</command>
	clause in the <command>zone</command> statement.
1354
      </para>
Mark Andrews's avatar
Mark Andrews committed
1355

1356
      <para>
1357 1358 1359
	If the zone's <command>update-policy</command> is set to
	<userinput>local</userinput>, updates to the zone
	will be permitted for the key <varname>local-ddns</varname>,
Evan Hunt's avatar
Evan Hunt committed
1360
	which will be generated by <command>named</command> at startup.
1361
	See <xref linkend="dynamic_update_policies"/> for more details.
1362 1363 1364
      </para>

      <para>
Evan Hunt's avatar
Evan Hunt committed
1365 1366 1367
	Dynamic updates using Kerberos signed requests can be made
	using the TKEY/GSS protocol by setting either the
	<command>tkey-gssapi-keytab</command> option, or alternatively
Mark Andrews's avatar
Mark Andrews committed
1368 1369
	by setting both the <command>tkey-gssapi-credential</command>
	and <command>tkey-domain</command> options. Once enabled,
Evan Hunt's avatar
Evan Hunt committed
1370 1371 1372
	Kerberos signed requests will be matched against the update
	policies for the zone, using the Kerberos principal as the
	signer for the request.
1373 1374 1375
      </para>

      <para>
Mark Andrews's avatar
NSEC3  
Mark Andrews committed
1376 1377 1378 1379 1380
	Updating of secure zones (zones using DNSSEC) follows RFC
	3007: RRSIG, NSEC and NSEC3 records affected by updates are
	automatically regenerated by the server using an online
	zone key.  Update authorization is based on transaction
	signatures and an explicit server policy.
1381 1382
      </para>

Evan Hunt's avatar
Evan Hunt committed
1383
      <section xml:id="journal"><info><title>The journal file</title></info>
1384

Evan Hunt's avatar
Evan Hunt committed
1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419
	<para>
	  All changes made to a zone using dynamic update are stored
	  in the zone's journal file.  This file is automatically created
	  by the server when the first dynamic update takes place.
	  The name of the journal file is formed by appending the extension
	  <filename>.jnl</filename> to the name of the