Bv9ARM-book.xml 604 KB
Newer Older
1
<!--
2
 - Copyright (C) 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 8 9
 -
 - See the COPYRIGHT file distributed with this work for additional
 - information regarding copyright ownership.
10
-->
Tinderbox User's avatar
Tinderbox User committed
11

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

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

46 47 48 49 50 51 52 53 54 55 56
    <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>

57
    <section xml:id="doc_scope"><info><title>Scope of Document</title></info>
58 59

      <para>
Evan Hunt's avatar
Evan Hunt committed
60 61 62 63 64 65 66
	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.
67
      </para>
Evan Hunt's avatar
Evan Hunt committed
68 69
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkgversion.xml"/>
    </section>
70

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

73
      <para>
Evan Hunt's avatar
Evan Hunt committed
74 75 76 77 78 79 80 81 82 83
	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
84
	certain options. The contents of <emphasis>Chapter 5</emphasis> are
Evan Hunt's avatar
Evan Hunt committed
85
	organized as in a reference manual to aid in the ongoing
86
	maintenance of the software. <emphasis>Chapter 6</emphasis> addresses
Evan Hunt's avatar
Evan Hunt committed
87
	security considerations, and
88
	<emphasis>Chapter 7</emphasis> contains troubleshooting help. The
Evan Hunt's avatar
Evan Hunt committed
89 90 91 92 93 94
	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.
95
      </para>
Evan Hunt's avatar
Evan Hunt committed
96
    </section>
97
    <section xml:id="conventions"><info><title>Conventions Used in This Document</title></info>
98 99

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

      <informaltable>
Evan Hunt's avatar
Evan Hunt committed
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 158 159 160
	<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>
161 162 163
      </informaltable>

      <para>
Evan Hunt's avatar
Evan Hunt committed
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 218 219 220
	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>
221
      </para>
Evan Hunt's avatar
Evan Hunt committed
222
    </section>
223 224
    <section xml:id="dns_overview"><info><title>The Domain Name System (<acronym>DNS</acronym>)</title></info>

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

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

	<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
248 249
	  contains a name server, <command>named</command>, and a set
	  of associated tools.
Evan Hunt's avatar
Evan Hunt committed
250 251
	</para>

252 253
	</section>
	<section xml:id="domain_names"><info><title>Domains and Domain Names</title></info>
Evan Hunt's avatar
Evan Hunt committed
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 298 299 300

	<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
301
      </section>
302

303 304
      <section xml:id="zones"><info><title>Zones</title></info>

Evan Hunt's avatar
Evan Hunt committed
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 354 355 356
	<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
357
      </section>
358

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

	<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>

377
	<section xml:id="primary_master"><info><title>The Primary Master</title></info>
Evan Hunt's avatar
Evan Hunt committed
378 379 380 381

	  <para>
	    The authoritative server where the master copy of the zone
	    data is maintained is called the
382
	    <emphasis>primary master</emphasis> server, or simply the
Evan Hunt's avatar
Evan Hunt committed
383 384 385 386
	    <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
387 388
	    <emphasis>zone file</emphasis> or
	    <emphasis>master file</emphasis>.
Evan Hunt's avatar
Evan Hunt committed
389
	  </para>
390 391 392 393 394 395

	  <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
396
	</section>
Evan Hunt's avatar
Evan Hunt committed
397

398 399
	<section xml:id="slave_server"><info><title>Slave Servers</title></info>

Evan Hunt's avatar
Evan Hunt committed
400 401 402
	  <para>
	    The other authoritative servers, the <emphasis>slave</emphasis>
	    servers (also known as <emphasis>secondary</emphasis> servers)
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427
	    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>
	  <para>
	    Periodically, the slave server must send a refresh query to
	    determine whether the zone contents have been updated. This
	    is done by sending a query for the zone's SOA record and
	    checking whether the SERIAL field has been updated; if so,
	    a new transfer request is initiated. The timing of these
	    refresh queries is controlled by the SOA REFRESH and RETRY
	    fields, but can be overrridden with the
	    <command>max-refresh-time</command>,
	    <command>min-refresh-time</command>,
	    <command>max-retry-time</command>, and
	    <command>min-retry-time</command> options.
	  </para>
	  <para>
	    If the zone data cannot be updated within the time specified
	    by the SOA EXPIRE option (up to a hard-coded maximum of
	    24 weeks) then the slave zone expires and will no longer
	    respond to queries.
Evan Hunt's avatar
Evan Hunt committed
428
	  </para>
Evan Hunt's avatar
Evan Hunt committed
429
	</section>
Evan Hunt's avatar
Evan Hunt committed
430

431
	<section xml:id="stealth_server"><info><title>Stealth Servers</title></info>
Evan Hunt's avatar
Evan Hunt committed
432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465

	  <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
466
	</section>
467

Evan Hunt's avatar
Evan Hunt committed
468
      </section>
469
      <section xml:id="cache_servers"><info><title>Caching Name Servers</title></info>
470

471
	<!--
472
	  - Terminology here is inconsistent.  Probably ought to
473 474 475 476
	  - convert to using "recursive name server" everywhere
	  - with just a note about "caching" terminology.
	  -->

Evan Hunt's avatar
Evan Hunt committed
477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503
	<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>

504
	<section xml:id="forwarder"><info><title>Forwarding</title></info>
Evan Hunt's avatar
Evan Hunt committed
505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528

	  <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
529
	</section>
530

Evan Hunt's avatar
Evan Hunt committed
531
      </section>
532

533
      <section xml:id="multi_role"><info><title>Name Servers in Multiple Roles</title></info>
Evan Hunt's avatar
Evan Hunt committed
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556

	<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>
557

Evan Hunt's avatar
Evan Hunt committed
558 559
      </section>
    </section>
560 561 562

  </chapter>

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

565
    <section xml:id="hw_req"><info><title>Hardware requirements</title></info>
566
      <para>
Evan Hunt's avatar
Evan Hunt committed
567 568 569 570
	<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.
571 572
      </para>
      <para>
Evan Hunt's avatar
Evan Hunt committed
573 574 575 576 577 578 579
	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.
580
      </para>
Evan Hunt's avatar
Evan Hunt committed
581
    </section>
582
    <section xml:id="cpu_req"><info><title>CPU Requirements</title></info>
583
      <para>
Evan Hunt's avatar
Evan Hunt committed
584 585 586 587 588
	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.
589
      </para>
Evan Hunt's avatar
Evan Hunt committed
590
    </section>
591
    <section xml:id="mem_req"><info><title>Memory Requirements</title></info>
592
      <para>
Evan Hunt's avatar
Evan Hunt committed
593 594 595 596 597 598
	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
599
	all zone and cache data into memory — unfortunately, the best
Evan Hunt's avatar
Evan Hunt committed
600 601 602 603 604
	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.
605
      </para>
606
      <!--
Evan Hunt's avatar
Evan Hunt committed
607
	- Add something here about leaving overhead for attacks?
608
	- How much overhead?  Percentage?
Evan Hunt's avatar
Evan Hunt committed
609
	-->
Evan Hunt's avatar
Evan Hunt committed
610
    </section>
611

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

614
      <para>
Evan Hunt's avatar
Evan Hunt committed
615 616 617 618 619 620 621 622 623 624 625
	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.
626
      </para>
Evan Hunt's avatar
Evan Hunt committed
627
    </section>
628

629 630
    <section xml:id="supported_os"><info><title>Supported Operating Systems</title></info>

631
      <para>
Evan Hunt's avatar
Evan Hunt committed
632 633
	ISC <acronym>BIND</acronym> 9 compiles and runs on a large
	number
Mark Andrews's avatar
Mark Andrews committed
634
	of Unix-like operating systems and on
Evan Hunt's avatar
Evan Hunt committed
635 636 637 638 639
	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.
640
      </para>
Evan Hunt's avatar
Evan Hunt committed
641
    </section>
642 643
  </chapter>

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

646
    <para>
647
      In this chapter we provide some suggested configurations along
648 649
      with guidelines for their use.  We suggest reasonable values for
      certain option settings.
650 651
    </para>

Evan Hunt's avatar
Evan Hunt committed
652
    <section xml:id="sample_configuration"><info><title>Sample Configurations</title></info>
653 654 655

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

Evan Hunt's avatar
Evan Hunt committed
656 657 658 659 660 661 662 663 664
	<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>
665 666

<programlisting>
667
// Two corporate subnets we wish to allow queries from.
668
acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
669
options {
670 671 672
     // Working directory
     directory "/etc/namedb";

673
     allow-query { corpnets; };
674
};
675 676
// Provide a reverse mapping for the loopback
// address 127.0.0.1
677 678 679 680 681 682
zone "0.0.127.in-addr.arpa" {
     type master;
     file "localhost.rev";
     notify no;
};
</programlisting>
683

Evan Hunt's avatar
Evan Hunt committed
684
      </section>
685

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

Evan Hunt's avatar
Evan Hunt committed
688 689 690 691 692
	<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>
693 694

<programlisting>
695
options {
696 697 698 699 700 701 702 703
     // 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;
704 705
};

706 707
// Provide a reverse mapping for the loopback
// address 127.0.0.1
708 709 710 711 712 713 714 715 716
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";
717 718
     // IP addresses of slave servers allowed to
     // transfer example.com
719
     allow-transfer {
Evan Hunt's avatar
Evan Hunt committed
720 721
	  192.168.4.14;
	  192.168.5.53;
722 723 724 725 726 727 728 729 730 731
     };
};
// 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>
732

Evan Hunt's avatar
Evan Hunt committed
733 734
      </section>
    </section>
735

736 737
    <section xml:id="load_balancing"><info><title>Load Balancing</title></info>

738
      <!--
Evan Hunt's avatar
Evan Hunt committed
739
	- Add explanation of why load balancing is fragile at best
740
	- and completely pointless in the general case.
Evan Hunt's avatar
Evan Hunt committed
741
	-->
742 743

      <para>
Evan Hunt's avatar
Evan Hunt committed
744 745
	A primitive form of load balancing can be achieved in
	the <acronym>DNS</acronym> by using multiple records
746
	(such as multiple A records) for one name.
747 748 749
      </para>

      <para>
Evan Hunt's avatar
Evan Hunt committed
750 751 752 753
	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:
754 755 756
      </para>

      <informaltable colsep="0" rowsep="0">
Evan Hunt's avatar
Evan Hunt committed
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 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869
	<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>
870 871
      </informaltable>
      <para>
Evan Hunt's avatar
Evan Hunt committed
872 873 874 875 876
	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.
877 878
      </para>
      <para>
Evan Hunt's avatar
Evan Hunt committed
879 880 881 882
	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"/>.
883 884
      </para>

Evan Hunt's avatar
Evan Hunt committed
885
    </section>
886

887
    <section xml:id="ns_operations"><info><title>Name Server Operations</title></info>
888

889
      <section xml:id="tools"><info><title>Tools for Use With the Name Server Daemon</title></info>
Evan Hunt's avatar
Evan Hunt committed
890 891 892 893 894 895
	<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
896
	<section xml:id="diagnostic_tools"><info><title>Diagnostic Tools</title></info>
Evan Hunt's avatar
Evan Hunt committed
897 898 899 900 901 902 903 904 905 906
	  <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
907
	      <term xml:id="dig"><command>dig</command></term>
Evan Hunt's avatar
Evan Hunt committed
908 909
	      <listitem>
		<para>
910
		  <command>dig</command>
Evan Hunt's avatar
Evan Hunt committed
911 912 913 914 915 916 917 918
		  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
919
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
920
		  <command>dig</command>
Evan Hunt's avatar
Evan Hunt committed
921 922 923 924 925 926 927
		  <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
928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953
		</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
954
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
955
		  <command>host</command>
Evan Hunt's avatar
Evan Hunt committed
956 957 958 959 960 961 962 963 964 965 966
		  <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
967 968 969 970 971 972 973 974 975 976 977
		</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>
978
	      <listitem>
Evan Hunt's avatar
Evan Hunt committed
979 980 981 982 983 984 985 986 987
		<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
988
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
989
		  <command>nslookup</command>
Evan Hunt's avatar
Evan Hunt committed
990 991 992 993
		  <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
994 995
		  </group>
		</cmdsynopsis>
996
		<para>
Evan Hunt's avatar
Evan Hunt committed
997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015
		  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.
1016
		</para>
Mark Andrews's avatar
Mark Andrews committed
1017
	      </listitem>
Evan Hunt's avatar
Evan Hunt committed
1018

1019
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1020
	  </variablelist>
Evan Hunt's avatar
Evan Hunt committed
1021
	</section>
1022

Evan Hunt's avatar
Evan Hunt committed
1023
	<section xml:id="admin_tools"><info><title>Administrative Tools</title></info>
Evan Hunt's avatar
Evan Hunt committed
1024 1025 1026 1027 1028
	  <para>
	    Administrative tools play an integral part in the management
	    of a server.
	  </para>
	  <variablelist>
Evan Hunt's avatar
Evan Hunt committed
1029
	    <varlistentry xml:id="named-checkconf" xreflabel="Named Configuration Checking application">
Evan Hunt's avatar
Evan Hunt committed
1030 1031 1032 1033 1034 1035 1036

	      <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
1037
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1038
		  <command>named-checkconf</command>
Evan Hunt's avatar
Evan Hunt committed
1039 1040 1041
		  <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
1042 1043 1044
		</cmdsynopsis>
	      </listitem>
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1045
	    <varlistentry xml:id="named-checkzone" xreflabel="Zone Checking application">
Evan Hunt's avatar
Evan Hunt committed
1046 1047 1048 1049 1050 1051 1052 1053

	      <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
1054
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1055
		  <command>named-checkzone</command>
Evan Hunt's avatar
Evan Hunt committed
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065
		  <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
1066 1067 1068
		</cmdsynopsis>
	      </listitem>
	    </varlistentry>
Evan Hunt's avatar
Evan Hunt committed
1069
	    <varlistentry xml:id="named-compilezone" xreflabel="Zone Compilation application">
Evan Hunt's avatar
Evan Hunt committed
1070 1071 1072 1073 1074 1075 1076 1077 1078
	      <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
1079
	    <varlistentry xml:id="rndc" xreflabel="Remote Name Daemon Control application">
Evan Hunt's avatar
Evan Hunt committed
1080 1081 1082 1083 1084 1085 1086 1087 1088

	      <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.
		  If you run <command>rndc</command> without any
1089
		  options, it will display a usage message as follows:
Evan Hunt's avatar
Evan Hunt committed
1090
		</para>
Evan Hunt's avatar
Evan Hunt committed
1091
		<cmdsynopsis label="Usage" sepchar=" ">
Evan Hunt's avatar
Evan Hunt committed
1092
		  <command>rndc</command>
Evan Hunt's avatar
Evan Hunt committed
1093 1094 1095 1096 1097 1098
		  <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
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
		</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>"
1187
		  have any meaning.  The secret is a Base64 encoded string
Evan Hunt's avatar
Evan Hunt committed
1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212
		  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>
1213
key rndc_key {
1214
     algorithm "hmac-sha256";
1215 1216
     secret
       "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
1217 1218
};
options {
1219
     default-server 127.0.0.1;
1220 1221 1222
     default-key    rndc_key;
};
</programlisting>
1223

Evan Hunt's avatar
Evan Hunt committed
1224 1225 1226 1227
		<para>
		  This file, if installed as <filename>/etc/rndc.conf</filename>,
		  would allow the command:
		</para>
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1228

Evan Hunt's avatar
Evan Hunt committed
1229 1230 1231
		<para>
		  <prompt>$ </prompt><userinput>rndc reload</userinput>
		</para>
1232

Evan Hunt's avatar
Evan Hunt committed
1233 1234 1235 1236 1237 1238
		<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
1239 1240

<programlisting>
1241
controls {
Evan Hunt's avatar
Evan Hunt committed
1242 1243
	inet 127.0.0.1
	    allow { localhost; } keys { rndc_key; };
1244 1245 1246
};
</programlisting>

Evan Hunt's avatar
Evan Hunt committed
1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271
		<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
1272 1273
	</section>
      </section>
1274

1275
      <section xml:id="signals"><info><title>Signals</title></info>
Evan Hunt's avatar
Evan Hunt committed
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 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319
	<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
1320 1321
      </section>
    </section>
Evan Hunt's avatar
Evan Hunt committed
1322 1323 1324

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="plugins.xml"/>

1325 1326
  </chapter>

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

Evan Hunt's avatar
Evan Hunt committed
1329
    <section xml:id="notify"><info><title>Notify</title></info>
1330
      <para>
Evan Hunt's avatar
Evan Hunt committed
1331 1332 1333 1334 1335
	<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.
1336 1337 1338
      </para>

      <para>
Evan Hunt's avatar
Evan Hunt committed
1339 1340 1341 1342 1343 1344
	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.
1345 1346
      </para>

Jeremy C. Reed's avatar
Jeremy C. Reed committed
1347
      <note><simpara>
1348
	As a slave zone can also be a master to other slaves, <command>named</command>,
Evan Hunt's avatar
Evan Hunt committed
1349
	by default, sends <command>NOTIFY</command> messages for every zone
1350
	it loads.  Specifying <command>notify master-only;</command> will
1351
	cause <command>named</command> to only send <command>NOTIFY</command> for master
1352
	zones that it loads.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1353
      </simpara></note>
1354

Evan Hunt's avatar
Evan Hunt committed
1355
    </section>
1356

Evan Hunt's avatar
Evan Hunt committed
1357
    <section xml:id="dynamic_update"><info><title>Dynamic Update</title></info>
1358 1359

      <para>
Evan Hunt's avatar
Evan Hunt committed
1360 1361 1362 1363
	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.
1364 1365 1366
      </para>

      <para>
1367
	Dynamic update is enabled by including an
1368 1369
	<command>allow-update</command> or an <command>update-policy</command>
	clause in the <command>zone</command> statement.
1370
      </para>
Mark Andrews's avatar
Mark Andrews committed
1371

1372
      <para>
1373 1374 1375
	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
1376
	which will be generated by <command>named</command> at startup.
Evan Hunt's avatar