Bv9ARM-book.xml 264 KB
Newer Older
1 2
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
3
               "/usr/local/share/xml/dtd/docbook/docbookx.dtd">
4

5
<!-- File: $Id: Bv9ARM-book.xml,v 1.5 2000/09/11 17:09:46 scanner Exp $ -->
6

7 8
<book>

9
  <chapter id="ch01">
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 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 158 159 160 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 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 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 298 299 300 301 302 303 304 305 306
  <title>Introduction </title>
  <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>

  <sect1>
    <title>Scope of Document</title>

    <para>The Berkeley Internet Name Domain (<acronym>BIND</acronym>) implements an
    Internet nameserver for a number of operating systems. This
    document provides basic information about the installation and
    care of the Internet Software Consortium (<acronym>ISC</acronym>) <acronym>BIND</acronym> version 9
    software package for system administrators.</para>
  </sect1>
  <sect1><title>Organization of This Document</title>
    <para>In this document, <emphasis>Section 1</emphasis> introduces
    the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Section 2</emphasis>
    describes resource requirements for running <acronym>BIND</acronym> in various
    environments. Information in <emphasis>Section 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>Section 4</emphasis>, which contains more advanced
    concepts that the system administrator may need for implementing
    certain options. Section 5 describes the <acronym>BIND</acronym> 9 lightweight
    resolver.  The contents of <emphasis>Section 6</emphasis> are
    organized as in a reference manual to aid in the ongoing
    maintenance of the software. <emphasis>Section 7
    </emphasis>addresses security considerations, and
    <emphasis>Section 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.</para>
  </sect1>
  <sect1><title>Conventions Used in This Document</title>

    <para>In this document, we use the following general typographic
    conventions:</para>

<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>a pathname, filename, URL, hostname,
mailing list name, or new term or concept</para></entry>
              <entry colname = "2" rowsep = "1"><para><filename>Italic</filename></para></entry>
            </row>
            <row rowsep = "0">
              <entry colname = "1" colsep = "1" rowsep = "1"><para>literal user
input</para></entry>
              <entry colname = "2" rowsep = "1"><para><userinput>Fixed Width Bold</userinput></para></entry>
            </row>
            <row rowsep = "0">
              <entry colname = "1" colsep = "1" rowsep = "1"><para>variable user
input</para></entry>
              <entry colname = "2" rowsep = "1"><para><optional>Fixed Width Italic</optional></para></entry>
            </row>
            <row rowsep = "0">
              <entry colname = "1" colsep = "1"><para>program output</para></entry>
              <entry colname = "2"><para><computeroutput>Fixed Width Bold</computeroutput></para></entry>
            </row>
          </tbody>
        </tgroup>
</informaltable>

    <para>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>Sans Serif Bold</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>Sans Serif Italic</varname></para></entry>
            </row>
<row rowsep = "0">
<entry colname = "1" colsep = "1" rowsep = "1"><para>"meta-syntactic"
information (within brackets when optional)</para></entry>
<entry colname = "2" rowsep = "1"><para><optional>Fixed Width Italic</optional></para></entry>
</row>
<row rowsep = "0">
<entry colname = "1" colsep = "1" rowsep = "1"><para>Command line
input</para></entry>
<entry colname = "2" rowsep = "1"><para><userinput>Fixed Width Bold</userinput></para></entry>
</row>
<row rowsep = "0">
<entry colname = "1" colsep = "1" rowsep = "1"><para>Program output</para></entry>
                <entry colname = "2" rowsep = "1"><para><computeroutput>Fixed Width</computeroutput></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></para></sect1>
<sect1><title>Discussion of Domain Name System (<acronym>DNS</acronym>) Basics and
<acronym>BIND</acronym></title>
<para>The purpose of this document is to explain the installation
and basic upkeep of the <acronym>BIND</acronym> software package, and we begin by reviewing
the fundamentals of the domain naming system as they relate to <acronym>BIND</acronym>.
<acronym>BIND</acronym> consists of a <emphasis>nameserver</emphasis> (or "daemon")
called <command>named</command> and a <command>resolver</command> library.
The <acronym>BIND</acronym> server runs in the background, servicing queries on a well
known network port. The standard port for the User Datagram Protocol
(UDP) and Transmission Control Protocol (TCP), usually port 53,
is specified in<command> </command><filename>/etc/services</filename>.
The <emphasis>resolver</emphasis> is a set of routines residing
in a system library that provides the interface that programs can
use to access the domain name services.</para>
<sect2><title>Nameservers</title>
<para>A nameserver (NS) is a program that stores information about
named resources and responds to queries from programs called <emphasis>resolvers</emphasis> which
act as client processes. The basic function of an NS is to provide
information about network objects by answering queries.</para>
<para>With the nameserver, the network can be broken into a hierarchy
of domains. The name space is organized as a tree according to organizational
or administrative boundaries. Each node of the tree, called a domain,
is given a label. The name of the domain is the concatenation of
all the labels of the domains from the root to the current domain.
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 domain. The whole name space is partitioned into areas
called <emphasis>zones</emphasis>, each starting at a domain and
extending down to the leaf domains or to domains where other zones
start. Zones usually represent administrative boundaries. For example,
a domain name for a host at the company <emphasis>Example, Inc.</emphasis> would
be:</para>
<para><systemitem class="systemname">ourhost.example.com</systemitem></para>
<para>where <systemitem class="systemname">com</systemitem> is the top level domain to which <systemitem class="systemname">ourhost.example.com</systemitem> belongs, <systemitem class="systemname">example</systemitem> is
a subdomain of <systemitem class="systemname">com</systemitem>, and <systemitem class="systemname">ourhost</systemitem> is the
name of the host.</para>
<para>The specifications for the domain nameserver are defined in
the RFC 1034, RFC 1035 and RFC 974. These documents can be found
in
<filename>/usr/src/etc/named/doc</filename> in 4.4BSD or are available
via File Transfer Protocol (FTP) from
<ulink
       url="ftp://www.isi.edu/in-notes/">ftp://www.isi.edu/in-notes/</ulink> or via the Web at <ulink url="http://www.ietf.org/rfc/">http://www.ietf.org/rfc/</ulink>.
(See Appendix C for complete information on finding and retrieving
RFCs.) It is also recommended that you read the related man pages: <command>named</command> and <command>resolver</command>.</para></sect2>
<sect2><title>Types of Zones</title>
<para>As we 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 domain 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 has one or more NS records in the
parent zone, which should be matched by equivalent NS records at
the root of the delegated zone.</para>
<para>To properly operate a nameserver, it is important to understand
the difference between a <emphasis>zone</emphasis> and a <emphasis>domain</emphasis>.</para>
<para>For instance, consider the <systemitem class="systemname">example.com</systemitem> domain
which includes names such as <systemitem class="systemname">host.aaa.example.com </systemitem>and <systemitem class="systemname">host.bbb.example.com</systemitem> even
though the <systemitem class="systemname">example.com</systemitem> zone includes only delegations
for the <systemitem class="systemname">aaa.example.com</systemitem> and <systemitem class="systemname">bbb.example.com</systemitem> 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
nameservers. 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 a Domain Nameserver, 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>
<para>Each zone will have one <emphasis>primary master</emphasis> (also
called <emphasis>primary</emphasis>) server which 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.
There there will be some number of <emphasis>slave</emphasis> (also
called <emphasis>secondary) </emphasis>servers, which load the zone
contents using the <acronym>DNS</acronym> protocol (that is, the secondary servers
will contact the primary and fetch the zone data using TCP). This
set of servers &mdash; the primary and all of its secondaries &mdash; should be
listed in the NS records in the parent zone and will constitute a <emphasis>delegation</emphasis>.
This set of servers must also be listed in the zone file itself,
usually under the <command>@</command> name which indicates the <emphasis>top
level</emphasis> or <emphasis>root</emphasis> of the current zone.
You can list servers in the zone's top-level <command>@</command> 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 in
the zone's <command>@</command>.</para>
<para>Any servers listed in the NS records must be configured as <emphasis>authoritative</emphasis> for
the zone. A server is authoritative for a zone when it has been
configured to answer questions for that zone with authority, which
it does by setting the "authoritative answer" (AA) bit in reply
packets. A server may be authoritative for more than one zone. The
authoritative data for a zone is composed of all of the Resource
Records (RRs) &mdash; the data associated with names in a tree-structured
name space &mdash; attached to all of the nodes from the top node of the
zone down to leaf nodes or nodes above cuts around the bottom edge
of the zone.</para>
<para>Adding a zone as a type master or type slave will tell the
server to answer questions for the zone authoritatively. If the
server is able to load the zone into memory without any errors it
will set the AA bit when it replies to queries for the zone. See
RFCs 1034 and 1035 for more information about the AA bit.</para></sect2>
<sect2><title>Servers</title>
<para>A <acronym>DNS</acronym> server can be master for some zones and slave for others
or can be only a master, or only a slave, or can serve no zones
and just answer queries via its <emphasis>cache</emphasis>. Master
servers are often also called <emphasis>primaries</emphasis> and
slave servers are often also called <emphasis>secondaries</emphasis>.
Both master/primary and slave/secondary servers are authoritative
for a zone.</para>
<para>All servers keep data in their cache until the data expires,
based on a Time To Live (TTL) field which is maintained for all
resource records.</para>
<sect3><title>Master Server</title>
<para>The <emphasis>primary master server</emphasis> is the ultimate
source of information about a domain. The primary master is an authoritative
server configured to be the source of zone transfer for one or more
secondary servers. The primary master server obtains data for the
zone from a file on disk.</para></sect3>
<sect3><title>Slave Server </title>
<para>A <emphasis>slave server</emphasis>, also called a <emphasis>secondary
server</emphasis>, is an authoritative server that uses zone transfers from
the primary master server to retrieve the zone data. Optionally,
the slave server obtains zone data from a cache on disk. Slave servers
provide necessary redundancy. All secondary/slave servers are named
in the NS RRs for the zone.</para></sect3>
<sect3><title>Caching Only Server</title>
<para>Some servers are <emphasis>caching only servers</emphasis>.
This means that the server caches the information that it receives
and uses it until the data expires. A caching only server is a server
that is not authoritative for any zone. This server services queries
and asks other servers, who have the authority, for the information
it needs.</para></sect3>
<sect3><title>Forwarding Server</title>
<para>Instead of interacting with the nameservers for the root and
other domains, a <emphasis>forwarding server</emphasis> always forwards
queries it cannot satisfy from its authoritative data or cache to
a fixed list of other servers. The forwarded queries are also known
as <emphasis>recursive queries</emphasis>, the same type as a client would
send to a server. There may be one or more servers forwarded to,
and they are queried in turn until the list is exhausted or an answer
is found. A forwarding server is typically used when you do not
wish all the servers at a given site to interact 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. An added benefit of using the forwarding
feature is that the central machine develops a much more complete
cache of information that all the workstations can take advantage
of.</para>
<para>There is no prohibition against declaring a server to be a
forwarder even though it has master and/or slave zones as well;
the effect will still be that anything in the local server's cache
or zones will be answered, and anything else will be forwarded using
the forwarders list.</para></sect3>
<sect3><title>Stealth Server</title>
<para>A <emphasis>stealth server</emphasis> is a server that answers
authoritatively for a zone, but is not listed in that zone's NS
records. Stealth servers can be used as a way to centralize distribution
of a zone, without having to edit the zone on a remote nameserver.
Where the master file for a zone resides on a stealth server in
this way, it is often referred to as a "hidden primary" configuration.
Stealth servers can also be a way to keep a local copy of a zone
for rapid access to the zone's records, even if all "official" nameservers
for the zone are inaccessible.</para>
      </sect3>
    </sect2>
  </sect1>
  </chapter>

307
  <chapter id="ch02"><title><acronym>BIND</acronym> Resource Requirements</title>
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 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
<sect1><title>Hardware requirements</title>
<para><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.</para>
<para>The DNSSEC and IPv6 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 now fully multithreaded, allowing full utilization of
multiprocessor systems for installations that need it.</para></sect1>
<sect1><title>CPU Requirements</title>
<para>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.</para></sect1>
<sect1><title>Memory Requirements </title>
<para>The memory of the server has to be large enough to fit the
cache and zones loaded off disk. Future releases of <acronym>BIND</acronym> 9 will
provide methods 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
all zone and cache data into memory &mdash; unfortunately, the best way
to determine this for a given installation is to watch the nameserver
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. Ideally, the resource limits should
be set higher than this stable size.</para></sect1>
<sect1><title>Nameserver Intensive Environment Issues</title>
<para>For nameserver intensive environments, there are two alternative
configurations that may be used. The first is where clients and
any second-level internal nameservers query a main nameserver, 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 nameservers 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 nameservers share their cached data.</para></sect1>
<sect1><title>Supported Operating Systems</title>
<para>ISC <acronym>BIND</acronym> 9 compiles and runs on the following operating
systems:</para>
    <itemizedlist>
      <listitem>
        <simpara>IBM AIX 4.3</simpara>
      </listitem>
      <listitem>
        <simpara>Compaq Digital/Tru64 UNIX 4.0D</simpara>
      </listitem>
      <listitem>
        <simpara>HP HP-UX 11</simpara>
      </listitem>
      <listitem>
        <simpara>IRIX64 6.5</simpara>
      </listitem>
      <listitem>
        <simpara>Red Hat Linux 6.0, 6.1</simpara>
      </listitem>
      <listitem>
        <simpara>Sun Solaris 2.6, 7, 8 (beta)</simpara>
      </listitem>
      <listitem>
        <simpara>FreeBSD 3.4-STABLE</simpara>
      </listitem>
      <listitem>
        <simpara>NetBSD-current with "unproven" pthreads</simpara>
      </listitem>
    </itemizedlist>
  </sect1>
  </chapter>

377
  <chapter id="ch03">
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 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 428 429 430 431 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 466 467 468 469 470 471 472 473 474 475 476 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 504 505 506 507 508 509 510 511 512 513 514 515 516 517
  <title>Nameserver Configuration</title>
<para>In this section we provide some suggested configurations along
with guidelines for their use. We also address the topic of reasonable
option setting.</para>
  <sect1 id="sample_configuration">
    <title>Sample Configurations</title>
    <sect2>
      <title>A Caching-only Nameserver</title>
      <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.</para>
      <programlisting>
// Two corporate subnets we wish to allow queries from.
acl "corpnets" { 192.168.4.0/24; 192.168.7.0/24; };
options {
     directory "/etc/namedb";		// Working directory
     pid-file "named.pid";		// Put pid file in working dir
     allow-query { "corpnets"; };
};
// Root server hints
zone "." { type hint; file "root.hint"; };
// Provide a reverse mapping for the loopback address 127.0.0.1
zone "0.0.127.in-addr.arpa" {
     type master;
     file "localhost.rev";
     notify no;
};
</programlisting>
    </sect2>
    <sect2>
      <title>An Authoritative-only Nameserver</title>
      <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>
      <programlisting>
options {
     directory "/etc/namedb";		// Working directory
     pid-file "named.pid";		// Put pid file in working dir
     allow-query { any; };		// This is the default
     recursion no;			// Do not provide recursive service
};
// Root server hints
zone "." { type hint; file "root.hint"; };

// Provide a reverse mapping for the loopback address 127.0.0.1
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";
     // IP addresses of slave servers allowed to transfer example.com
     allow-transfer {
          192.168.4.14;
          192.168.5.53;
     };
};
// 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>
    </sect2>
  </sect1>
  <sect1>
    <title>Load Balancing</title>
    <para>Primitive load balancing can be achieved in <acronym>DNS</acronym> using multiple
A records for one name.</para>
<para>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:</para>
    <informaltable colsep = "0" rowsep = "0">
<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></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></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>
    </informaltable>
    <para>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.</para>
    <para>For more detail on ordering responses, check the
    <command>rrset-order</command> substatement in the
    <command>options</command> statement, see <xref
                                                endterm="rrset_ordering_title" linkend="rrset_ordering"/>. This substatement is not supported in
    <acronym>BIND</acronym> 9, and only the ordering scheme described above is
    available.</para>

  </sect1>
  <sect1 id="notify">
    <title>Notify</title>

    <para><acronym>DNS</acronym> Notify is a mechanism that allows master nameservers 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 transfer.</para> <para><acronym>DNS</acronym>
    Notify is fully documented in RFC 1996. See also the description
518
    of the zone option <command>also-notify</command>, see <xref
519
    linkend="zone_transfers"/>. For more information about
520
    <command>notify</command>, see <xref
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 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
    linkend="boolean_options"/>.</para>

  </sect1>
  <sect1>
    <title>Nameserver Operations</title>
    <sect2>
      <title>Tools for Use With the Nameserver Daemon</title>
      <para>There are several indispensable diagnostic, administrative
and monitoring tools available to the system administrator for controlling
and debugging the nameserver daemon. We describe several in this
section </para>
      <sect3>
        <title>Diagnostic Tools</title>
        <variablelist>
          <varlistentry>
            <term><command>dig</command></term>
            <listitem>
              <para>The domain information groper (<command>dig</command>) is
a command line tool that can be used to gather information from
the Domain Name System servers. Dig 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>
              <cmdsynopsis label="Usage">
                        <command>dig</command>
                        <arg>@<replaceable>server</replaceable></arg>
                        <arg choice="plain"><replaceable>domain</replaceable></arg>
                        <arg><replaceable>query-type</replaceable></arg>
                        <arg><replaceable>query-class</replaceable></arg>
                        <arg>+<replaceable>query-option</replaceable></arg>
                        <arg>-<replaceable>dig-option</replaceable></arg>
                        <arg>%<replaceable>comment</replaceable></arg>
                <!-- one of (SBR GROUP ARG COMMAND) -->
              </cmdsynopsis>
              <para>The usual simple use of dig 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
provides a simple <acronym>DNS</acronym> lookup using a command-line interface for
looking up Internet hostnames. By default, the utility converts
between host names and Internet addresses, but its functionality
can be extended with the use of options.</para>
              <cmdsynopsis label="Usage">
                <!-- one of (SBR GROUP ARG COMMAND) -->
                <command>host</command>
                <arg>-aCdlrTwv</arg>
                <arg>-c <replaceable>class</replaceable></arg>
                <arg>-N <replaceable>ndots</replaceable></arg>
                <arg>-t <replaceable>type</replaceable></arg>
                <arg>-W <replaceable>timeout</replaceable></arg>
                <arg>-R <replaceable>retries</replaceable></arg>
                <arg choice="plain"><replaceable>hostname</replaceable></arg>
                <arg><replaceable>server</replaceable></arg>
              </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>
            <listitem>
              <para><command>nslookup</command> is a program used to query Internet
domain nameservers. <command>nslookup</command> has two modes: interactive
and non-interactive. Interactive mode allows the user to query nameservers
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>
              <cmdsynopsis label="Usage">
                <command>nslookup</command>
                <arg rep="repeat">-option</arg>
                <group>
                  <arg><replaceable>host-to-find</replaceable></arg>
                  <arg>- <arg>server</arg></arg>
                </group>
              </cmdsynopsis>
<para>Interactive mode is entered when no arguments are given (the
default nameserver will be used) or when the first argument is a
hyphen (`-') and the second argument is the host name or Internet address
of a nameserver.</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 nameserver.</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.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>
      <sect3>
        <title>Administrative Tools</title>
        <para>Administrative tools play an integral part in the management
of a server.</para>
        <variablelist>
          <varlistentry>
            <term id="rndc"><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 nameserver.
              If you run <command>rndc</command> without any options
              it will display a usage message as follows:</para>
              <cmdsynopsis label="Usage">
                <command>rndc</command>
                <arg>-c <replaceable>config</replaceable></arg>
                <arg>-s <replaceable>server</replaceable></arg>
                <arg>-p <replaceable>port</replaceable></arg>
                <arg>-y <replaceable>key</replaceable></arg>
                <arg choice="plain"><replaceable>command</replaceable></arg>
                <arg rep="repeat"><replaceable>command</replaceable></arg>
              </cmdsynopsis>
              <para><command>command</command> is one of the following
              for <command>named</command>:</para>
              <informaltable colsep = "0" rowsep = "0">
                <tgroup cols = "2"
                        colsep = "0" rowsep = "0" tgroupstyle = "4Level-table">
                  <colspec colname = "1" colnum = "1"
                           colsep = "0" colwidth = "1.500in"/>
                  <colspec colname = "2" colnum = "2" colsep = "0"
                           colwidth = "3.000in"/>
                  <tbody>
                    <row rowsep = "0">
                      <entry colname = "1">
<para><userinput>status</userinput><footnote id="nyi1">
                            <para>not yet implemented</para>
                          </footnote></para></entry>
<entry colname = "2"><para>Display ps(1) status of named.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><userinput>dumpdb</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Dump database and cache to /var/tmp/named_dump.db.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><userinput>reload</userinput></para></entry>
<entry colname = "2"><para>Reload configuration file and zones.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><userinput>stats</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Dump statistics to /var/tmp/named.stats.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><userinput>trace</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Increment debugging level by one.</para></entry>
</row>
<row rowsep = "0">
                      <entry colname = "1">
<para><userinput>notrace</userinput><footnoteref linkend="nyi1"/>
</para></entry>
<entry colname = "2"><para>Set debugging level to 0.</para></entry>
</row>
<row rowsep = "0">
                      <entry colname =
                             "1"><para><userinput>querylog</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Toggle query logging.</para></entry>
</row>
<row rowsep = "0">
                      <entry colname =
                             "1"><para><userinput>stop</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Stop the server.</para></entry>
</row>
<row rowsep = "0">
                      <entry colname =
                             "1"><para><userinput>restart</userinput><footnoteref linkend="nyi1"/></para></entry>
<entry colname = "2"><para>Restart the server.</para></entry>
                    </row>
                  </tbody>
                </tgroup>
              </informaltable>
              <para>As noted above, <command>reload</command> is the
              only command available for <acronym>BIND</acronym> 9.0.0. The other
              commands, and more, are planned to be implemented for
              future releases.</para>

              <para>A configuration file is required, 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.</para>

              <para>The format of the configuration file is similar to
              that of <filename>named.conf</filename>, but limited to
              only three statements, the <command>options{}</command>,
              <command>key{}</command> and <command>server{}</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 two clauses: <command>default-server</command> and <command>default-key</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 key as its argument, as defined by a <command>key{}</command> statement.
 In the future a <command>default-port</command> clause will be
added to specify the port to which <command>rndc</command> should
connect.</para>
<para>The <command>key{}</command> statement names a key with its
string argument. The string is required by the server to 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 string "<userinput>hmac-md5</userinput>"
has any meaning.  The secret is a base-64 encoded string, typically
generated with either <command>dnssec-keygen</command> or <command>mmencode</command>.</para>
<para>The <command>server{}</command> statement uses the key clause
to associate a <command>key{}</command>-defined key with a server.
 The argument to the <command>server{}</command> statement is a
host name or address (addresses must be double quoted).  The argument
to the key clause is the name of the key as defined by the <command>key{}</command> statement.
 A <command>port</command> clause will be added to a future release
to specify the port to which <command>rndc</command> should connect
on the given server.</para>
<para>A sample minimal configuration file is as follows:</para>
              <programlisting>
key rndc_key {
     algorithm "hmac-md5";
     secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
};
options {
     default-server localhost;
     default-key    rndc_key;
};
</programlisting>
<para>This file, if installed as <filename>/etc/rndc.conf</filename>,
would allow the command:</para>
              <para><prompt>$ </prompt><userinput>rndc reload</userinput></para>
<para>to connect to 127.0.0.1 port 953 and cause the nameserver
to reload, if a nameserver on the local machine were running with
following controls statements:</para>
              <programlisting>
controls {
		inet 127.0.0.1 allow { localhost; } keys { rndc_key; };
};
</programlisting>
<para>and it had an identical key statement for
<literal>rndc_key</literal>.</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect3>
    </sect2>
    <sect2>
      <title>Signals</title>
<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 colsep = "0" rowsep = "0"><tgroup cols = "2"
    colsep = "0" rowsep = "0" tgroupstyle = "3Level-table">
<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>
    </sect2>
  </sect1>
  </chapter>

806
  <chapter id="ch04">
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
  <title>Advanced Concepts</title>
  <sect1 id="dynamic_update">
    <title>Dynamic Update</title>

    <para>Dynamic update is the term used for the ability under
    certain specified conditions to add, modify or delete records or
    RRsets in the master zone files. Dynamic update is fully described
    in RFC 2136.</para>

    <para>Dynamic update is enabled on a zone-by-zone basis, by
    including an <command>allow-update</command> or
    <command>update-policy</command> clause in the
    <command>zone</command> statement.</para>

    <para>Updating of secure zones (zones using DNSSEC) is modelled
    after the <emphasis>simple-secure-update</emphasis> proposal, a
    work in progress in the DNS Extensions working group of the IETF.
    (See <ulink
    url="http://www.ietf.org/html.charters/dnsext-charter.html">http://www.ietf.org/html.charters/dnsext-charter.html</ulink>
    for information about the DNS Extensions working group.) SIG and
    NXT 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.</para>

    <para>The zone files of dynamic zones must not be edited by hand.
    The zone file on disk at any given time may not contain the latest
    changes performed by dynamic update. The zone file is written to
    disk only periodically, and changes that have occurred since the
    zone file was last written to disk are stored only in the zone's
    journal (<filename>.jnl</filename>) file. <acronym>BIND</acronym> 9 currently does
    not update the zone file when it exits as <acronym>BIND</acronym> 8 does, so editing
    the zone file manually is unsafe even when the server has been
    shut down. </para>
  </sect1>
  <sect1 id="incremental_zone_transfers">
    <title>Incremental Zone Transfers (IXFR)</title>

    <para>The incremental zone transfer (IXFR) protocol is a way for
    slave servers to transfer only changed data, instead of having to
    transfer the entire zone. The IXFR protocol is documented in RFC
847
    1995. See <xref linkend="proposed_standards"/></para>
848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 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 934 935 936 937 938 939 940 941 942 943 944 945 946

<para>When acting as a master, <acronym>BIND</acronym> 9 supports IXFR for those zones
where the necessary change history information is available. These
include master zones maintained by dynamic update and slave zones
whose data was obtained by IXFR, but not manually maintained master
zones nor slave zones obtained by performing a full zone transfer
(AXFR).</para>
<para>When acting as a slave, <acronym>BIND</acronym> 9 will attempt to use IXFR unless
it is explicitly disabled. For more information about disabling
IXFR, see the description of the <command>request-ixfr</command> clause
of the <command>server</command> statement.</para></sect1>
<sect1><title>Split DNS</title>
<para>Setting up different views, or visibility, of DNS space to
internal and external resolvers is usually referred to as a <emphasis>Split
DNS</emphasis> setup. There are several reasons an organization
would want to set up its DNS this way.</para>
<para>One common reason for setting up a DNS system this way is
to hide "internal" DNS information from "external" clients on the
Internet. There is some debate as to whether or not this is actually useful.
Internal DNS information leaks out in many ways (via email headers,
for example) and most savvy "attackers" can find the information
they need using other means.</para>
<para>Another common reason for setting up a Split DNS system is
to allow internal networks that are behind filters or in RFC 1918
space (reserved IP space, as documented in RFC 1918) to resolve DNS
on the Internet. Split DNS can also be used to allow mail from outside
back in to the internal network.</para>
<para>Here is an example of a split DNS setup:</para>
<para>Let's say a company named <emphasis>Example, Inc.</emphasis> (example.com)
has several corporate sites that have an internal network with reserved
Internet Protocol (IP) space and an external demilitarized zone (DMZ),
or "outside" section of a network, that is available to the public.</para>
<para><emphasis>Example, Inc.</emphasis> wants its internal clients
to be able to resolve external hostnames and to exchange mail with
people on the outside. The company also wants its internal resolvers
to have access to certain internal-only zones that are not available
at all outside of the internal network.</para>
<para>In order to accomplish this, the company will set up two sets
of nameservers. One set will be on the inside network (in the reserved
IP space) and the other set will be on bastion hosts, which are "proxy"
hosts that can talk to both sides of its network, in the DMZ.</para>
<para>The internal servers will be configured to forward all queries,
except queries for <filename>site1.internal</filename>, <filename>site2.internal</filename>, <filename>site1.example.com</filename>,
and <filename>site2.example.com</filename>, to the servers in the
DMZ. These internal servers will have complete sets of information
for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>,<emphasis> </emphasis><filename>site1.internal</filename>,
and <filename>site2.internal</filename>.</para>
<para>To protect the<filename> site1.interna</filename><emphasis>l</emphasis> and<emphasis> </emphasis><filename>site2.internal</filename> domains,
the internal nameservers must be configured to disallow all queries
to these domains from any external hosts, including the bastion
hosts.</para>
<para>The external servers, which are on the bastion hosts, will
be configured to serve the "public" version of the <filename>site1</filename> and <filename>site2.example.com</filename> zones.
This could include things such as the host records for public servers
(<filename>www.example.com</filename> and <filename>ftp.example.com</filename>),
and mail exchange (MX)  records (<filename>a.mx.example.com</filename> and <filename>b.mx.example.com</filename>).</para>
<para>In addition, the public <filename>site1</filename> and <filename>site2.example.com</filename> zones
should have special MX records that contain wildcard (`*') records
pointing to the bastion hosts. This is needed because external mail
servers do not have any other way of looking up how to deliver mail
to those internal hosts. With the wildcard records, the mail will
be delivered to the bastion host, which can then forward it on to
internal hosts.</para>
<para>Here's an example of a wildcard MX record:</para>
<programlisting><literal>*   IN MX 10 external1.example.com.</literal></programlisting>
<para>Now that they accept mail on behalf of anything in the internal
network, the bastion hosts will need to know how to deliver mail
to internal hosts. In order for this to work properly, the resolvers on
the bastion hosts will need to be configured to point to the internal
nameservers for DNS resolution.</para>
<para>Queries for internal hostnames will be answered by the internal
servers, and queries for external hostnames will be forwarded back
out to the DNS servers on the bastion hosts.</para>
<para>In order for all this to work properly, internal clients will
need to be configured to query <emphasis>only</emphasis> the internal
nameservers for DNS queries. This could also be enforced via selective
filtering on the network.</para>
<para>If everything has been set properly, <emphasis>Example, Inc.</emphasis>'s
internal clients will now be able to:</para>
<itemizedlist><listitem>
        <simpara>Look up any hostnames in the <systemitem class="systemname">site1</systemitem> and 
<systemitem class="systemname">site2.example.com</systemitem> zones.</simpara></listitem>
<listitem>
        <simpara>Look up any hostnames in the <systemitem class="systemname">site1.internal</systemitem> and 
<systemitem class="systemname">site2.internal</systemitem> domains.</simpara></listitem>
<listitem>
        <simpara>Look up any hostnames on the Internet.</simpara></listitem>
<listitem>
        <simpara>Exchange mail with internal AND external people.</simpara></listitem></itemizedlist>
<para>Hosts on the Internet will be able to:</para>
<itemizedlist><listitem>
        <simpara>Look up any hostnames in the <systemitem class="systemname">site1</systemitem> and 
<systemitem class="systemname">site2.example.com </systemitem>zones.</simpara></listitem>
<listitem>
        <simpara>Exchange mail with anyone in the <systemitem class="systemname">site1</systemitem> and 
<systemitem class="systemname">site2.example.com</systemitem> zones.</simpara></listitem></itemizedlist>

    <para>Here is an example configuration for the setup we just
    described above. Note that this is only configuration information;
947
    for information on how to configure your zone files, see <xref
948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056
    linkend="sample_configuration"/></para>

<para>Internal DNS server config:</para>
<programlisting>
acl internals { 172.16.72.0/24; 192.168.1.0/24;
};
acl externals { <varname>bastion-ips-go-here</varname>; };
options {
    ...
    ...
    forward only;
    forwarders { <varname>bastion-ips-go-here</varname>; }; // forward to external
servers
    allow-transfer { none; };															// sample allow-transfer
(no one)
    allow-query { internals; externals; };															// restrict
query access
    allow-recursion { internals; };															// restrict recursion
    ...
    ...
};
zone "site1.example.com" { 															//
sample slave zone
  type master;
  file "m/site1.example.com";
  forwarders { }; 															// do normal iterative
															// resolution (do not forward)
  allow-query { internals; externals; };
  allow-transfer { internals; };
};
zone "site2.example.com" {
  type slave;
  file "s/site2.example.com";
  masters { 172.16.72.3; };
  forwarders { };
  allow-query { internals; externals; };
  allow-transfer { internals; };
};
zone "site1.internal" {
  type master;
  file "m/site1.internal";
  forwarders { };
  allow-query { internals; };
  allow-transfer { internals; }
};
zone "site2.internal" {
  type slave;
  file "s/site2.internal";
  masters { 172.16.72.3; };
  forwarders { };
  allow-query { internals };
  allow-transfer { internals; }
};
</programlisting>
    <para>External (bastion host) DNS server config:</para>
<programlisting>
acl internals { 172.16.72.0/24; 192.168.1.0/24;
};
acl externals { bastion-ips-go-here; };
options {
  ...
  ...
  allow-transfer { none; };															// sample allow-transfer
(no one)
  allow-query { internals; externals; };															// restrict
query access
  allow-recursion { internals; externals; };															// restrict
recursion
  ...
  ...
};
zone "site1.example.com" {															//
sample slave zone
  type master;
  file "m/site1.foo.com";
  allow-query { any; };
  allow-transfer { internals; externals; };
};
zone "site2.example.com" {
  type slave;
  file "s/site2.foo.com";
  masters { another_bastion_host_maybe; };
  allow-query { any; };
  allow-transfer { internals; externals; }
};
</programlisting>
<para>In the <filename>resolv.conf</filename> (or equivalent) on
the bastion host(s):</para>
<programlisting>
search ...
nameserver 172.16.72.2
nameserver 172.16.72.3
nameserver 172.16.72.4
</programlisting>
</sect1>
<sect1 id="tsig"><title>TSIG</title>
<para>This is a short guide to setting up Transaction SIGnatures
(TSIG) based transaction security in <acronym>BIND</acronym>. It describes changes
to the configuration file as well as what changes are required for
different features, including the process of creating transaction
keys and using transaction signatures with <acronym>BIND</acronym>.</para>
<para><acronym>BIND</acronym> primarily supports TSIG for server to server communication.
This includes zone transfer, notify, and recursive query messages.
Resolvers based on newer versions of <acronym>BIND</acronym> 8 have limited support
for TSIG.</para>

    <para>TSIG might be most useful for dynamic update. A primary
    server for a dynamic zone should use access control to control
    updates, but IP-based access control is insufficient. Key-based
1057
    access control is far superior, see <xref
1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 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
    linkend="proposed_standards"/>. The <command>nsupdate</command>
    program supports TSIG via the <option>-k</option> and
    <option>-y</option> command line options.</para>

<sect2><title>Generate Shared Keys for Each Pair of Hosts</title>
<para>A shared secret is generated to be shared between <emphasis>host1</emphasis> and <emphasis>host2</emphasis>.
An arbitrary key name is chosen: "host1-host2.". The key name must
be the same on both hosts.</para>
<sect3><title>Automatic Generation</title>
<para>The following command will generate a 128 bit (16 byte) HMAC-MD5
key as described above. Longer keys are better, but shorter keys
are easier to read. Note that the maximum key length is 512 bits;
keys longer than that will be digested with MD5 to produce a 128
bit key.</para>
        <para><userinput>dnssec-keygen -a hmac-md5 -b 128 -n HOST host1-host2.</userinput></para>
<para>The key is in the file <filename>Khost1-host2.+157+00000.private</filename>.
Nothing directly uses this file, but the base-64 encoded string
following "<literal>Key:</literal>"
can be extracted from the file and used as a shared secret:</para>
<programlisting>Key: La/E5CjG9O+os1jq0a2jdA==</programlisting>
<para>The string "<literal>La/E5CjG9O+os1jq0a2jdA==</literal>" can
be used as the shared secret.</para></sect3>
<sect3><title>Manual Generation</title>
<para>The shared secret is simply a random sequence of bits, encoded
in base-64. Most ASCII strings are valid base-64 strings (assuming
the length is a multiple of 4 and only valid characters are used),
so the shared secret can be manually generated.</para>
<para>Also, a known string can be run through <command>mmencode</command> or
a similar program to generate base-64 encoded data.</para></sect3></sect2>
<sect2><title>Copying the Shared Secret to Both Machines</title>
<para>This is beyond the scope of DNS. A secure transport mechanism
should be used. This could be secure FTP, ssh, telephone, etc.</para></sect2>
<sect2><title>Informing the Servers of the Key's Existence</title>
<para>Imagine <emphasis>host1</emphasis> and <emphasis>host 2</emphasis> are
both servers. The following is added to each server's <filename>named.conf</filename> file:</para>
<programlisting>
key host1-host2. {
  algorithm hmac-md5;
  secret "La/E5CjG9O+os1jq0a2jdA==";
};
</programlisting>
<para>The algorithm, hmac-md5, is the only one supported by <acronym>BIND</acronym>.
The secret is the one generated above. Since this is a secret, it
is recommended that either <filename>named.conf</filename> be non-world
readable, or the key directive be added to a non-world readable
file that is included by <filename>named.conf</filename>.</para>
<para>At this point, the key is recognized. This means that if the
server receives a message signed by this key, it can verify the
signature. If the signature succeeds, the response is signed by
the same key.</para></sect2>
<sect2><title>Instructing the Server to Use the Key</title>
<para>Since keys are shared between two hosts only, the server must
be told when keys are to be used. The following is added to the <filename>named.conf</filename> file
for <emphasis>host1</emphasis>, if the IP address of <emphasis>host2</emphasis> is
10.1.2.3:</para>
<programlisting>
server 10.1.2.3 {
  keys { host1-host2. ;};
};
</programlisting>
<para>Multiple keys may be present, but only the first is used.
This directive does not contain any secrets, so it may be in a world-readable
file.</para>
<para>If <emphasis>host1</emphasis> sends a message that is a response
to that address, the message will be signed with the specified key. <emphasis>host1</emphasis> will
expect any responses to signed messages to be signed with the same
key.</para>
<para>A similar statement must be present in <emphasis>host2</emphasis>'s
configuration file (with <emphasis>host1</emphasis>'s address) for <emphasis>host2</emphasis> to
sign non-response messages to <emphasis>host1</emphasis>.</para></sect2>
<sect2><title>TSIG Key Based Access Control</title>
<para><acronym>BIND</acronym> allows IP addresses and ranges to be specified in ACL
definitions and
<command>allow-{ query | transfer | update } </command>directives.
This has been extended to allow TSIG keys also. The above key would
be denoted <command>key host1-host2.</command></para>
<para>An example of an allow-update directive would be:</para>
<programlisting>
allow-update { key host1-host2. ;};
</programlisting>

      <para>This allows dynamic updates to succeed only if the request
      was signed by a key named
1141 1142
      "<command>host1-host2.</command>".</para> <para>You may want to read about the more
      powerful <command>update-policy</command> statement in <xref
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 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 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 1259 1260 1261 1262 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 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398
      linkend="dynamic_update_policies"/>.</para>

    </sect2>
    <sect2>
      <title>Errors</title>

      <para>The processing of TSIG signed messages can result in
      several errors. If a signed message is sent to a non-TSIG aware
      server, a FORMERR will be returned, since the server will not
      understand the record. This is a result of misconfiguration,
      since the server must be explicitly configured to send a TSIG
      signed message to a specific server.</para>

      <para>If a TSIG aware server receives a message signed by an
      unknown key, the response will be unsigned with the TSIG
      extended error code set to BADKEY. If a TSIG aware server
      receives a message with a signature that does not validate, the
      response will be unsigned with the TSIG extended error code set
      to BADSIG. If a TSIG aware server receives a message with a time
      outside of the allowed range, the response will be signed with
      the TSIG extended error code set to BADTIME, and the time values
      will be adjusted so that the response can be successfully
      verified. In any of these cases, the message's rcode is set to
      NOTAUTH.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>TKEY</title>

    <para><command>TKEY</command> is a mechanism for automatically
    generating a shared secret between two hosts.  There are several
    "modes" of <command>TKEY</command> that specify how the key is
    generated or assigned.  <acronym>BIND</acronym> implements only one of these modes,
    the Diffie-Hellman key exchange.  Both hosts are required to have
    a Diffie-Hellman KEY record (although this record is not required
    to be present in a zone).  The <command>TKEY</command> process
    must use signed messages, signed either by TSIG or SIG(0).  The
    result of <command>TKEY</command> is a shared secret that can be
    used to sign messages with TSIG.  <command>TKEY</command> can also
    be used to delete shared secrets that it had previously
    generated.</para>

    <para>The <command>TKEY</command> process is initiated by a client
    or server by sending a signed <command>TKEY</command> query
    (including any appropriate KEYs) to a TKEY-aware server.  The
    server response, if it indicates success, will contain a
    <command>TKEY</command> record and any appropriate keys.  After
    this exchange, both participants have enough information to
    determine the shared secret; the exact process depends on the
    <command>TKEY</command> mode.  When using the Diffie-Hellman
    <command>TKEY</command> mode, Diffie-Hellman keys are exchanged,
    and the shared secret is derived by both participants.</para>
  
  </sect1>
  <sect1>
    <title>SIG(0)</title>

    <para><acronym>BIND</acronym> 9 partially supports DNSSEC SIG(0) transaction
    signatures as specified in RFC 2535.  SIG(0) uses public/private
    keys to authenticate messages.  Access control is performed in the
    same manner as TSIG keys; privileges can be granted or denied
    based on the key name.</para>

    <para>When a SIG(0) signed message is received, it will only be
    verified if the key is known and trusted by the server; the server
    will not attempt to locate and/or validate the key.</para>

    <para><acronym>BIND</acronym> 9 does not ship with any tools that generate SIG(0)
    signed messages.</para>

  </sect1>
  <sect1 id="DNSSEC">
    <title>DNSSEC</title>

    <para>Cryptographic authentication of DNS information is possible
    through the DNS Security (<emphasis>DNSSEC</emphasis>) extensions,
    defined in RFC 2535. This section describes the creation and use
    of DNSSEC signed zones.</para>

    <para>In order to set up a DNSSEC secure zone, there are a series
    of steps which must be followed.  <acronym>BIND</acronym> 9 ships with several tools
    that are used in this process, which are explained in more detail
    below.  In all cases, the "<option>-h</option>" option prints a
    full list of parameters.</para>

    <para>There must also be communication with the administrators of
    the parent and/or child zone to transmit keys and signatures.  A
    zone's security status must be indicated by the parent zone for a
    DNSSEC capable resolver to trust its data.</para>

    <para>For other servers to trust data in this zone, they must
    either be statically configured with this zone's zone key or the
    zone key of another zone above this one in the DNS tree.</para>

    <sect2>
      <title>Generating Keys</title>

      <para>The <command>dnssec-keygen</command> program is used to
      generate keys.</para>

      <para>A secure zone must contain one or more zone keys.  The
      zone keys will sign all other records in the zone, as well as
      the zone keys of any secure delegated zones.  Zone keys must
      have the same name as the zone, a name type of
      <command>ZONE</command>, and must be usable for authentication.
      It is recommended that zone keys be mandatory to implement a
      cryptographic algorithm; currently the only key mandatory to
      implement an algorithm is DSA.</para>

      <para>The following command will generate a 768 bit DSA key for
      the <filename>child.example</filename> zone:</para>

      <para><userinput>dnssec-keygen -a DSA -b 768 -n ZONE child.example.</userinput></para>

      <para>Two output files will be produced:
      <filename>Kchild.example.+003+12345.key</filename> and
      <filename>Kchild.example.+003+12345.private</filename> (where
      12345 is an example of a key tag).  The key file names contain
      the key name (<filename>child.example.</filename>), algorithm (3
      is DSA, 1 is RSA, etc.), and the key tag (12345 in this case).
      The private key (in the <filename>.private</filename> file) is
      used to generate signatures, and the public key (in the
      <filename>.key</filename> file) is used for signature
      verification.</para>

      <para>To generate another key with the same properties (but with
      a different key tag), repeat the above command.</para>

      <para>The public keys should be inserted into the zone file with
      <command>$INCLUDE</command> statements, including the
      <filename>.key </filename>files.</para>

    </sect2>
    <sect2>
      <title>Creating a Keyset</title>

      <para>The <command>dnssec-makekeyset</command> program is used
      to create a key set from one or more keys.</para>

      <para>Once the zone keys have been generated, a key set must be
      built for transmission to the administrator of the parent zone,
      so that the parent zone can sign the keys with its own zone key
      and correctly indicate the security status of this zone.  When
      building a key set, the list of keys to be included and the TTL
      of the set must be specified, and the desired signature validity
      period of the parent's signature may also be specified.</para>

      <para>The list of keys to be inserted into the key set may also
      included non-zone keys present at the top of the zone.
      <command>dnssec-makekeyset</command> may also be used at other
      names in the zone.</para>

      <para>The following command generates a key set containing the
      above key and another key similarly generated, with a TTL of
      3600 and a signature validity period of 10 days starting from
      now.</para>

<para><userinput>dnssec-makekeyset -t 3600 -e +86400 Kchild.example.+003+12345 Kchild.example.+003+23456</userinput></para>

      <para>One output file is produced:
      <filename>child.example.keyset</filename>.  This file should be
      transmitted to the parent to be signed.  It includes the keys,
      as well as signatures over the key set generated by the zone
      keys themselves, which are used to prove ownership of the
      private keys and encode the desired validity period.</para>

    </sect2>
    <sect2>
      <title>Signing the Child's Keyset</title>

      <para>The <command>dnssec-signkey</command> program is used to
      sign one child's keyset.</para>

      <para>If the <filename>child.example</filename> zone has any
      delegations which are secure, for example,
      <filename>grand.child.example</filename>, the
      <filename>child.example</filename> administrator should receive
      keyset files for each secure subzone.  These keys must be signed
      by this zone's zone keys.</para>

      <para>The following command signs the child's key set with the
      zone keys:</para>

<para><userinput>dnssec-signkey grand.child.example.keyset Kchild.example.+003+12345 Kchild.example.+003+23456</userinput></para>

      <para>One output file is produced:
      <filename>grand.child.example.signedkey</filename>.  This file
      should be both transmitted back to the child and retained.  It
      includes all keys (the child's keys) from the keyset file and
      signatures generated by this zone's zone keys.</para>

    </sect2>
    <sect2>
      <title>Signing the Zone</title>

      <para>The <command>dnssec-signzone</command> program is used to
      sign a zone.</para>

      <para>Any <filename>signedkey</filename> files corresponding to
      secure subzones should be present, as well as a
      <filename>signedkey</filename> file for this zone generated by
      the parent (if there is one). The zone signer will generate
      <literal>NXT</literal> and <literal>SIG</literal> records for
      the zone, as well as incorporate the zone key signature from the
      parent and indicate the security status at all delegation
      points.</para>

      <para>The following command signs the zone, assuming it is in a
      file called <filename>zone.child.example</filename>.  By
      default, all zone keys which have an available private key are
      used to generate signatures.</para>

<para><userinput>dnssec-signzone -o child.example zone.child.example</userinput></para>

      <para>One output file is produced:
      <filename>zone.child.example.signed</filename>.  This file
      should be referenced by <filename>named.conf</filename> as the
      input file for the zone.</para>

    </sect2>
    <sect2><title>Configuring Servers</title>

      <para>Unlike in <acronym>BIND</acronym> 8, data is not verified on load in <acronym>BIND</acronym> 9,
      so zone keys for authoritative zones do not need to be specified
      in the configuration file.</para>

      <para>The public key for any security root must be present in
      the configuration file's <command>trusted-keys</command>
      statement, as described later in this document. </para>

    </sect2>
  </sect1>
  <sect1>
    <title>IPv6 Support in <acronym>BIND</acronym> 9</title>

    <para><acronym>BIND</acronym> 9 fully supports all currently defined forms of IPv6
    name to address and address to name lookups.  It will also use
    IPv6 addresses to make queries when running on an IPv6 capable
    system.</para>

    <para>For forward lookups, <acronym>BIND</acronym> 9 supports both A6 and AAAA
    records.  The of AAAA records is deprecated, but it is still
    useful for hosts to have both AAAA and A6 records to maintain
    backward compatibility with installations where AAAA records are
    still used.  In fact, the stub resolvers currently shipped with
    most operating system support only AAAA lookups, because following
    A6 chains is much harder than doing A or AAAA lookups.</para>

    <para>For IPv6 reverse lookups, <acronym>BIND</acronym> 9 supports the new
    "bitstring" format used in the <emphasis>ip6.arpa</emphasis>
    domain, as well as the older, deprecated "nibble" format used in
    the <emphasis>ip6.int</emphasis> domain.</para>

    <para><acronym>BIND</acronym> 9 includes a new lightweight resolver library and
    resolver daemon which new applications may choose to use to avoid
1399
    the complexities of A6 chain following and bitstring labels, see <xref
1400
    linkend="ch05"/>.</para>
1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584

    <sect2>
      <title>Address Lookups Using AAAA Records</title>

      <para>The AAAA record is a parallel to the IPv4 A record.  It
      specifies the entire address in a single record.  For
      example,</para>

<programlisting>
$ORIGIN example.com.
host					1h		IN	AAAA	3ffe:8050:201:1860:42::1
</programlisting>

      <para>While their use is deprecated, they are useful to support
      older IPv6 applications.  They should not be added where they
      are not absolutely necessary.</para>

    </sect2>
    <sect2>
      <title>Address Lookups Using A6 Records</title>

      <para>The A6 record is more flexible than the AAAA record, and
      is therefore more complicated.  The A6 record can be used to
      form a chain of A6 records, each specifying part of the IPv6
      address. It can also be used to specify the entire record as
      well.  For example, this record supplies the same data as the
      AAAA record in the previous example:</para>

<programlisting>
$ORIGIN example.com.
host					1h		IN	A6	0	3ffe:8050:201:1860:42::1
</programlisting>
      <sect3>
        <title>A6 Chains</title>

        <para>A6 records are designed to allow network
        renumbering. This works when an A6 record only specifies the
        part of the address space the domain owner controls.  For
        example, a host may be at a company named "company."  It has
        two ISPs which provide IPv6 address space for it.  These two
        ISPs fully specify the IPv6 prefix they supply.</para>

        <para>In the company's address space:</para>

<programlisting>
$ORIGIN	example.com.
host			1h	IN	A6	64	0:0:0:0:42::1											company.example1.net.
host			1h	IN	A6	64	0:0:0:0:42::1					company.example2.net.
</programlisting>

        <para>ISP1 will use:</para>

<programlisting>
$ORIGIN example1.net.
company				1h		IN		A6	0	3ffe:8050:201:1860::
</programlisting>

<para>ISP2 will use:</para>

<programlisting>
$ORIGIN example2.net.
company				1h		IN		A6	0	1234:5678:90ab:fffa::
</programlisting>

        <para>When <systemitem
        class="systemname">host.example.com</systemitem> is looked up,
        the resolver (in the resolver daemon or caching name server)
        will find two partial A6 records, and will use the additional
        name to find the remainder of the data.</para>

      </sect3>
      <sect3>
        <title>A6 Records for DNS Servers</title>

        <para>When an A6 record specifies the address of a name
        server, it should use the full address rather than specifying
        a partial address.  For example:</para>

<programlisting>
$ORIGIN example.com.
@			4h		IN		NS		ns0
			4h		IN		NS		ns1
ns0			4h		IN		A6		0						3ffe:8050:201:1860:42::1
ns1			4h		IN		A		192.168.42.1
</programlisting>

        <para>It is recommended that IPv4-in-IPv6 mapped addresses not
        be used.  If a host has an IPv4 address, use an A record, not
        an A6, with <literal>::ffff:192.168.42.1</literal> as the
        address.</para>

      </sect3>
    </sect2>
    <sect2>
      <title>Address to Name Lookups Using Nibble Format</title>

      <para>While the use of nibble format to look up names is
      deprecated, it is supported for backwards compatiblity with
      existing IPv6 applications.</para>

      <para>When looking up an address in nibble format, the address
      components are simply reversed, just as in IPv4, and
      <literal>ip6.int.</literal> is appended to the resulting name.
      For example, the following would provide reverse name lookup for
      a host with address
      <literal>3ffe:8050:201:1860:42::1</literal>.</para>

<programlisting>
$ORIGIN 0.6.8.1.1.0.2.0.0.5.0.8.e.f.f.3.ip6.int.
1.0.0.0.0.0.0.0.0.0.0.0.2.4.0.0				4h										IN		PTR		host.example.com.
</programlisting>
    </sect2>
    <sect2>
      <title>Address to Name Lookups Using Bitstring Format</title>

      <para>Bitstring labels can start and end on any bit boundary,
      rather than on a multiple of 4 bits as in the nibble
      format. They also use <emphasis>ip6.arpa</emphasis> rather than
      <emphasis>ip6.int</emphasis>.</para>

      <para>To replicate the previous example using bitstrings:</para>

<programlisting>
$ORIGIN \[x3ffe805002011860/64].ip6.arpa.
\[x0042000000000001/64]									4h			IN			PTR			host.example.com.
</programlisting>
    </sect2>
    <sect2>
      <title>Using DNAME for Delegation of IPv6 Reverse Addresses</title>

      <para>In IPV6, the same host may have many addresses from many
      network providers.  Since the trailing portion of the address
      usually remains constant, <command>DNAME</command> can help
      reduce the number of zone files used for reverse mapping that
      need to be maintained.</para>

      <para>For example, consider a host which has two providers
      (<systemitem class="systemname">example.net</systemitem> and
      <systemitem class="systemname">example2.net</systemitem>) and
      therefore two IPv6 addresses.  Since the host chooses its own 64
      bit host address portion, the provider address is the only part
      that changes:</para>

<programlisting>
$ORIGIN example.com.
host						A6		64		::1234:5678:1212:5675 cust1.example.net.
						A6		64		::1234:5678:1212:5675 subnet5.example2.net.
$ORIGIN example.net.
cust1						A6		48		0:0:0:dddd:: ipv6net.example.net.
ipv6net						A6		0		aa:bb:cccc::
$ORIGIN example2.net.
subnet5						A6		48		0:0:0:1:: ipv6net2.example2.net.
ipv6net2						A6		0		6666:5555:4::
</programlisting>

<para>This sets up forward lookups.  To handle the reverse lookups,
the provider <systemitem class="systemname">example.net</systemitem>
would have:</para>

<programlisting>
$ORIGIN \[x00aa00bbcccc/48].ip6.arpa.
\[xdddd/16]								DNAME		ipv6-rev.example.com.
</programlisting>

      <para>and <systemitem
      class="systemname">example2.net</systemitem> would have:</para>

<programlisting>
$ORIGIN \[x666655550004/48].ip6.arpa.
\[x0001/16]								DNAME		ipv6-rev.example.com.
</programlisting>

      <para><systemitem class="systemname">example.com</systemitem>
      needs only one zone file to handle both of these reverse
      mappings:</para>

<programlisting>
$ORIGIN ipv6-rev.example.com.
\[x1234567812125675/64]								PTR				host.example.com. 
</programlisting>
    </sect2>
  </sect1>
  </chapter>

1585
  <chapter id="ch05"><title>The <acronym>BIND</acronym> 9 Lightweight Resolver</title>
1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617
<sect1><title>The Lightweight Resolver Library</title>
<para>Traditionally applications have been linked with a stub resolver
library that sends recursive DNS queries to a local caching name
server.</para>
<para>IPv6 introduces new complexity into the resolution process,
such as following A6 chains and DNAME records, and simultaneous
lookup of IPv4 and IPv6 addresses.  These are hard or impossible
to implement in a traditional stub resolver.</para>
<para>Instead, <acronym>BIND</acronym> 9 provides resolution services to local clients
using a combination of a lightweight resolver library and a resolver
daemon process running on the local host.  These communicate using
a simple UDP-based protocol, the "lightweight resolver protocol"
that is distinct from and simpler than the full DNS protocol.</para></sect1>
<sect1><title>Running a Resolver Daemon</title>
<para>To use the lightweight resolver interface, the system must
run the resolver daemon <command>lwresd</command>.</para>
<para>Applications using the lightweight resolver library will make
UDP requests to the IPv4 loopback address (127.0.0.1) on port 921.
 The daemon will try to find the answer to the questions "what are the
addresses for host <systemitem class="systemname">foo.example.com</systemitem>?" and "what are
the names for IPv4 address 204.152.184.79?"</para>
<para>The daemon currently only looks in the DNS, but in the future
it may use other sources such as <literal>/etc/hosts</literal>,
NIS, etc.</para>
<para>The <command>lwresd</command> daemon is essentially a stripped-down,
caching-only name server that answers requests using the lightweight
resolver protocol rather than the DNS protocol.  Because it needs
to run on each host, it is designed to require no or minimal configuration.
 It uses the name servers listed on <command>nameserver</command> lines
in <filename>/etc/resolv.conf</filename> as forwarders, but is also
capable of doing the resolution autonomously if none are specified.</para></sect1></chapter>

1618
<chapter id="ch06"><title><acronym>BIND</acronym> 9 Configuration Reference</title>
1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642
<para><acronym>BIND</acronym> 9 configuration is broadly similar to <acronym>BIND</acronym> 8.x; however,
there are a few new areas of configuration, such as views. <acronym>BIND</acronym>
8.x configuration files should work with few alterations in <acronym>BIND</acronym>
9, although more complex configurations should be reviewed to check
if they can be more efficiently implemented using the new features
found in <acronym>BIND</acronym> 9.</para>
<para><acronym>BIND</acronym> 4 configuration files can be converted to the new format
using the shell script
<filename>contrib/named-bootconf/named-bootconf.sh</filename>.</para>
<sect1 id="configuration_file_elements"><title>Configuration File Elements</title>
<para>Following is a list of elements used throughout the <acronym>BIND</acronym> configuration
file documentation:</para>
<informaltable colsep = "0"  rowsep = "0"><tgroup cols = "2"
    colsep = "0" rowsep = "0" tgroupstyle = "2Level-table">
<colspec colname = "1" colnum = "1" colsep = "0" colwidth = "1.855in"/>
<colspec colname = "2" colnum = "2" colsep = "0" colwidth = "3.770in"/>
<tbody>
<row rowsep = "0">
<entry colname = "1"><para><varname>acl_name</varname></para></entry>
<entry colname = "2"><para>The name of an <varname>address_match_list</varname> as
defined by the <command>acl</command> statement.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>address_match_list</varname></para></entry>
1643
<entry colname = "2"><para>A list of one or more <varname>ip_addr</varname><command>, </command><varname>ip_prefix</varname><command>, </command><varname>key_id</varname><command>, </command>or <varname>acl_name</varname> elements, see
1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048
<xref linkend="address_match_lists"/>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>domain_name</varname></para></entry>
<entry colname = "2"><para>A quoted string which will be used as
a DNS name, for example "<systemitem class="systemname">my.test.domain</systemitem>".</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>dotted_decimal</varname></para></entry>
<entry colname = "2"><para>One or more integers valued 0 through
255 separated only by dots (`.'), such as <command>123</command>, <command>45.67</command> or <command>89.123.45.67</command>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>ip4_addr</varname></para></entry>
<entry colname = "2"><para>An IPv4 address with exactly four elements
in <varname>dotted_decimal</varname> notation.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>ip6_addr</varname></para></entry>
<entry colname = "2"><para>An IPv6 address, such as <command>fe80::200:f8ff:fe01:9742</command>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>ip_addr</varname></para></entry>
<entry colname = "2"><para>An <varname>ip4_addr</varname> or<command> </command><varname>ip6_addr</varname>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>ip_port</varname></para></entry>
<entry colname = "2"><para>An IP port <varname>number</varname>.
 <varname>number</varname> is limited to 0 through 65535, with values
below 1024 typically restricted to root-owned processes. In some
cases an asterisk (`*') character can be used as a placeholder to
select a random high-numbered port.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>ip_prefix</varname></para></entry>
<entry colname = "2"><para>An IP network specified as an <varname>ip_addr</varname>,
followed by a slash (`/') and then the number of bits in the netmask.
For example, <command>127/8</command> is the network <command>127.0.0.0</command> with
netmask <command>255.0.0.0</command> and <command>1.2.3.0/28</command> is
network <command>1.2.3.0</command> with netmask <command>255.255.255.240</command>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>key_id</varname></para></entry>
<entry colname = "2"><para>A <varname>domain_name</varname> representing
the name of a shared key, to be used for transaction security.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>key_list</varname></para></entry>
<entry colname = "2"><para>A list of one or more <varname>key_id</varname>s,
separated by semicolons and ending with a semicolon.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>number</varname></para></entry>
<entry colname = "2"><para>A non-negative integer with an entire
range limited by the range of a C language signed integer (2,147,483,647
on a machine with 32 bit integers). Its acceptable value might further
be limited by the context in which it is used.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>path_name</varname></para></entry>
<entry colname = "2"><para>A quoted string which will be used as
a pathname, such as <filename>zones/master/my.test.domain</filename>.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>size_spec</varname></para></entry>
<entry colname = "2"><para>A number, the word <userinput>unlimited</userinput>,
or the word <userinput>default</userinput>.</para><para>The maximum
value of <varname>size_spec</varname> is that of unsigned long integers
on the machine. An <varname>unlimited</varname> <varname>size_spec</varname> requests unlimited
use, or the maximum available amount. A <varname>default size_spec</varname> uses
the limit that was in force when the server was started.</para><para>A <varname>number</varname> can
optionally be followed by a scaling factor: <userinput>K</userinput> or <userinput>k</userinput><command> </command>for
kilobytes, <userinput>M</userinput> or <userinput>m</userinput> for
megabytes, and <userinput>G</userinput> or <userinput>g</userinput> for gigabytes,
which scale by 1024, 1024*1024, and 1024*1024*1024 respectively.</para><para>Integer
storage overflow is currently silently ignored during conversion
of scaled values, resulting in values less than intended, possibly
even negative. Using <varname>unlimited</varname> is the best way
to safely set a really large number.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><varname>yes_or_no</varname></para></entry>
<entry colname = "2"><para>Either <userinput>yes</userinput> or <userinput>no</userinput>.
The words <userinput>true</userinput> and <userinput>false</userinput> are
also accepted, as are the numbers <userinput>1</userinput> and <userinput>0</userinput>.</para></entry>
</row>
</tbody>
</tgroup></informaltable>
<sect2 id="address_match_lists"><title>Address Match Lists</title>
<sect3><title>Syntax</title>
        <programlisting><varname>address_match_list</varname> = address_match_list_element ;
  <optional> address_match_list_element; ... </optional>
<varname>address_match_list_element</varname> = <optional> ! </optional> (ip_address <optional>/length</optional> |
   key key_id | acl_name | { address_match_list } )
</programlisting>
</sect3>
<sect3><title>Definition and Usage</title>
<para>Address match lists are primarily used to determine access
control for various server operations. They are also used to define
priorities for querying other nameservers and to set the addresses
on which <command>named</command> will listen for queries. The elements
which constitute an address match list can be any of the following:</para>
<itemizedlist><listitem>
            <simpara>an IP address (IPv4 or IPv6)</simpara></listitem>
<listitem>
            <simpara>an IP prefix (in the `/'-notation)</simpara></listitem>
<listitem>
            <simpara>a key ID, as defined by the key statement</simpara></listitem>
<listitem>
            <simpara>the name of an address match list previously defined with
the <command>acl</command> statement</simpara></listitem>
<listitem>
            <simpara>a nested address match list enclosed in braces</simpara></listitem></itemizedlist>
<para>Elements can be negated with a leading exclamation mark (`!')
and the match list names "any," "none," "localhost" and "localnets"
are predefined. More information on those names can be found in
the description of the acl statement.</para>
<para>The addition of the key clause made the name of this syntactic
element something of a misnomer, since security keys can be used
to validate access without regard to a host or network address. Nonetheless,
the term "address match list" is still used throughout the documentation.</para>
<para>When a given IP address or prefix is compared to an address
match list, the list is traversed in order until an element matches.
The interpretation of a match depends on whether the list is being used
for access control, defining listen-on ports, or as a topology,
and whether the element was negated.</para>
<para>When used as an access control list, a non-negated match allows
access and a negated match denies access. If there is no match,
access is denied. The clauses <command>allow-query</command>, <command>allow-transfer</command>, <command>allow-update</command> and <command>blackhole</command> all
use address match lists  this. Similarly, the listen-on option will cause
the server to not accept queries on any of the machine's addresses
which do not match the list.</para>
<para>When used with the topology clause, a non-negated match returns
a distance based on its position on the list (the closer the match
is to the start of the list, the shorter the distance is between
it and the server). A negated match will be assigned the maximum
distance from the server. If there is no match, the address will
get a distance which is further than any non-negated list element,
and closer than any negated element.</para>
<para>Because of the first-match aspect of the algorithm, an element
that defines a subset of another element in the list should come
before the broader element, regardless of whether either is negated. For
example, in
<command>1.2.3/24; ! 1.2.3.13;</command> the 1.2.3.13 element is
completely useless because the algorithm will match any lookup for
1.2.3.13 to the 1.2.3/24 element. Using <command>! 1.2.3.13; 1.2.3/24</command> fixes
that problem by having 1.2.3.13 blocked by the negation but all
other 1.2.3.* hosts fall through.</para></sect3></sect2>
    <sect2>
      <title>Comment Syntax</title>

      <para>The <acronym>BIND</acronym> 9 comment syntax allows for comments to appear
      anywhere that white space may appear in a <acronym>BIND</acronym> configuration
      file. To appeal to programmers of all kinds, they can be written
      in C, C++, or shell/perl constructs.</para>

      <sect3>
        <title>Syntax</title>

        <para><programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting>
<programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting>
<programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells and perl</programlisting>
      </para>
      </sect3>
      <sect3>
        <title>Definition and Usage</title>
<para>Comments may appear anywhere that whitespace may appear in
a <acronym>BIND</acronym> configuration file.</para>
<para>C-style comments start with the two characters /* (slash,
star) and end with */ (star, slash). Because they are completely
delimited with these characters, they can be used to comment only
a portion of a line or to span multiple lines.</para>
<para>C-style comments cannot be nested. For example, the following
is not valid because the entire comment ends with the first */:</para>
        <para><programlisting>/* This is the start of a comment.
   This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
   This is no longer in any comment. */
</programlisting></para>

<para>C++-style comments start with the two characters // (slash,
slash) and continue to the end of the physical line. They cannot
be continued across multiple physical lines; to have one logical
comment span multiple lines, each line must use the // pair.</para>
<para>For example:</para>
        <para><programlisting>// This is the start of a comment.  The next line
// is a new comment, even though it is logically
// part of the previous comment.
</programlisting></para>
<para>Shell-style (or perl-style, if you prefer) comments start
with the character <literal>#</literal> (number sign) and continue to the end of the
physical line, as in C++ comments.</para>
<para>For example:</para>
        <para><programlisting># This is the start of a comment.  The next line
# is a new comment, even though it is logically
# part of the previous comment.
</programlisting></para>
        <warning>
          <para>WARNING: you cannot use the semicolon (`;') character
          to start a comment such as you would in a zone file. The
          semicolon indicates the end of a configuration
          statement.</para>
        </warning>
      </sect3>
    </sect2>
  </sect1>
  <sect1 id="Configuration_File_Grammar">
    <title>Configuration File Grammar</title>

    <para>A <acronym>BIND</acronym> 9 configuration consists of statements and comments.
    Statements end with a semicolon. Statements and comments are the
    only elements that can appear without enclosing braces. Many
    statements contain a block of substatements, which are also
    terminated with a semicolon.</para>

    <para>The following statements are supported:</para>

    <informaltable colsep = "0"  rowsep = "0">
      <tgroup cols = "2" colsep = "0" rowsep = "0" tgroupstyle =
              "2Level-table">
        <colspec colname = "1" colnum = "1" colsep = "0" colwidth = "1.336in"/>
        <colspec colname = "2" colnum = "2" colsep = "0" colwidth = "3.778in"/>
        <tbody>
          <row rowsep = "0">
            <entry colname = "1"><para><command>acl</command></para></entry>
            <entry colname = "2"><para>defines a named IP address
matching list, for access control and other uses.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>controls</command></para></entry>
            <entry colname = "2"><para>declares control channels to be used
by the <command>rndc</command> utility.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>include</command></para></entry>
            <entry colname = "2"><para>includes a file.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>key</command></para></entry>
            <entry colname = "2"><para>specifies key information for use in
authentication and authorization using TSIG.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>logging</command></para></entry>
            <entry colname = "2"><para>specifies what the server logs, and where
the log messages are sent.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>options</command></para></entry>
            <entry colname = "2"><para>controls global server configuration
options and sets defaults for other statements.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>server</command></para></entry>
            <entry colname = "2"><para>sets certain configuration options on
a per-server basis.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>trusted-keys</command></para></entry>
            <entry colname = "2"><para>defines trusted DNSSEC keys.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>view</command></para></entry>
            <entry colname = "2"><para>defines a view.</para></entry>
          </row>
          <row rowsep = "0">
            <entry colname = "1"><para><command>zone</command></para></entry>
            <entry colname = "2"><para>defines a zone.</para></entry>
          </row>
        </tbody>
      </tgroup></informaltable>
    
    <para>The <command>logging</command> and
    <command>options</command> statements may only occur once per
    configuration.</para>

    <sect2>
      <title><command>acl</command> Statement Grammar</title>

      <programlisting><command>acl</command> acl-name { 
    address_match_list 
};
</programlisting>
    </sect2>
    <sect2 id="acl">
      <title><command>acl</command> Statement Definition and
Usage</title>

      <para>The <command>acl</command> statement assigns a symbolic
      name to an address match list. It gets its name from a primary
      use of address match lists: Access Control Lists (ACLs).</para>

      <para>Note that an address match list's name must be defined
      with <command>acl</command> before it can be used elsewhere; no
      forward references are allowed.</para>

      <para>The following ACLs are built-in:</para>

      <informaltable colsep = "0"  rowsep = "0"><tgroup cols = "2"
    colsep = "0" rowsep = "0" tgroupstyle = "3Level-table">
<colspec colname = "1" colnum = "1" colsep = "0" colwidth = "1.130in"/>
<colspec colname = "2" colnum = "2" colsep = "0" colwidth = "4.000in"/>
<tbody>
<row rowsep = "0">
<entry colname = "1"><para><command>any</command></para></entry>
<entry colname = "2"><para>Matches all hosts.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>none</command></para></entry>
<entry colname = "2"><para>Matches no hosts.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>localhost</command></para></entry>
<entry colname = "2"><para>Matches the IP addresses of all interfaces
on the system.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>localnets</command></para></entry>
<entry colname = "2"><para>Matches any host on a network for which
the system has an interface.</para></entry>
</row>
</tbody>
</tgroup></informaltable>
    </sect2>
    <sect2>
      <title><command>controls</command> Statement Grammar</title>
<programlisting><command>controls</command> {
   inet ( ip_addr | * ) <optional> port ip_port </optional> allow <replaceable> address_match_list </replaceable>
                keys <replaceable> key_list </replaceable>;
   <optional> inet ...; </optional>
};
</programlisting>
    </sect2>
    <sect2>
      <title><command>controls</command> Statement Definition and
Usage</title>

      <para>The <command>controls</command> statement declares control
      channels to be used by system administrators to affect the
      operation of the local nameserver. These control channels are
      used by the <command>rndc</command> utility to send commands to
      and retrieve non-DNS results from a nameserver.</para>

      <para>An <command>inet</command> control channel is a TCP/IP
      socket accessible to the Internet, created at the specified
      <command>ip_port</command> on the specified
      <command>ip_addr</command>.  If no port is specified, port 953
      is used by default.  "*" cannot be used for
      <command>ip_port</command>.</para>

      <para>The ability to issue commands over the control channel is
      restricted by the <command>allow</command> and
      <command>keys</command> clauses.  Connections to the control
      channel are permitted based on the address permissions in
      <command>address_match_list</command>. <command>key_id</command>
      members of the <command>address_match_list</command> are
      ignored, and instead are interpreted independently based the
      <command>key_list</command>.  Each <command>key_id</command> in
      the <command>key_list</command> is allowed to be used to
      authenticate commands and responses given over the control
      channel by digitally signing each message between the server and
      a command client (<xref linkend="rndc"/>). All commands to the
      control channel must be signed by one of its specified keys to
      be honored.</para>

      <para> For the initial release of <acronym>BIND</acronym> 9.0.0, only one command
      is possible over the command channel, the command to reload the
      server.  We will expand command set in future releases.</para>

      <para>The UNIX control channel type of <acronym>BIND</acronym> 8 is not supported
      in <acronym>BIND</acronym> 9.0.0, and is not expected to be added in future
      releases.  If it is present in the controls statement from a
      <acronym>BIND</acronym> 8 configuration file, a non-fatal warning will be
      logged.</para>

    </sect2>
    <sect2>
      <title><command>include</command> Statement Grammar</title>
      <programlisting>include <replaceable>filename</replaceable>;</programlisting>
    </sect2>
    <sect2>
      <title><command>include</command> Statement Definition and
Usage</title>

      <para>The <command>include</command> statement inserts the
      specified file at the point that the <command>include</command>
      statement is encountered. The <command>include</command>
      statement facilitates the administration of configuration files
      by permitting the reading or writing of some things but not
      others. For example, the statement could include private keys
      that are readable only by a nameserver.</para>

    </sect2>
    <sect2>
      <title><command>key</command> Statement Grammar</title>
      <programlisting>key <replaceable>key_id</replaceable> {
    algorithm <replaceable>string</replaceable>;
    secret <replaceable>string</replaceable>;
};
</programlisting>
    </sect2>
    <sect2>
      <title><command>key</command> Statement Definition and Usage</title>

      <para>The <command>key</command> statement defines a shared
2049
      secret key for use with TSIG, see <xref linkend="tsig"/>.</para>
2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340

      <para>The <replaceable>key_id</replaceable>, also known as the
      key name, is a domain name uniquely identifying the key. It can
      be used in a "server" statement to cause requests sent to that
      server to be signed with this key, or in address match lists to
      verify that incoming requests have been signed with a key
      matching this name, algorithm, and secret.</para>

      <para>The <replaceable>algorithm_id</replaceable> is a string
      that specifies a security/authentication algorithm. The only
      algorithm currently supported with TSIG authentication is
      <literal>hmac-md5</literal>.  The
      <replaceable>secret_string</replaceable> is the secret to be
      used by the algorithm, and is treated as a base-64 encoded
      string.</para>

</sect2>
    <sect2>
      <title><command>logging</command> Statement Grammar</title>
      <programlisting><command>logging</command> {
   [ <command>channel</command> <replaceable>channel_name</replaceable> {
     ( <command>file</command> <replaceable>path name</replaceable>
         [ <command>versions</command> ( <replaceable>number</replaceable> | <literal>unlimited</literal> ) ]
         [ <command>size</command> <replaceable>size spec</replaceable> ]
       | <command>syslog</command> ( <replaceable>syslog_facility</replaceable> )
       | <literal>null</literal> );
     [ <command>severity</command> (<option>critical</option> | <option>error</option> | <option>warning</option> | <option>notice</option> |
                 <option>info</option> | <option>debug</option> [ <replaceable>level</replaceable> ] | <option>dynamic</option> ); ]
     [ <command>print-category</command> <option>yes</option> or <option>no</option>; ]
     [ <command>print-severity</command> <option>yes</option> or <option>no</option>; ]
     [ <command>print-time</command> <option>yes</option> or <option>no</option>; ]
   }; ]
   [ <command>category</command> <replaceable>category_name</replaceable> {
     <replaceable>channel_name</replaceable> ; [ <replaceable>channel_nam</replaceable>e ; ... ]
   }; ]
   ...
};
</programlisting>
    </sect2>
    <sect2><title><command>logging</command> Statement Definition and
Usage</title>
<para>The <command>logging</command> statement configures a wide
variety of logging options for the nameserver. Its <command>channel</command> phrase
associates output methods, format options and severity levels with
a name that can then be used with the <command>category</command> phrase
to select how various classes of messages are logged.</para>
<para>Only one <command>logging</command> statement is used to define
as many channels and categories as are wanted. If there is no <command>logging</command> statement,
the logging configuration will be:</para>
      <programlisting><command>logging</command> {
     category "default" { "default_syslog"; "default_debug"; };
	};
</programlisting>
      <para>In <acronym>BIND</acronym> 9, the logging configuration is only established when
the entire configuration file has been parsed.  In <acronym>BIND</acronym> 8, it was
established as soon as the <command>logging</command> statement
was parsed. When the server is starting up, all logging messages
regarding syntax errors in the configuration file go to the default
channels, or to standard error if the "<option>-g</option>" option
was specified.</para>
      <sect3><title>The <command>channel</command> Phrase</title>
        <para>All log output goes to one or more <emphasis>channels</emphasis>;
you can make as many of them as you want.</para>
        <para>Every channel definition must include a clause that says whether
messages selected for the channel go to a file, to a particular
syslog facility, or are discarded. It can optionally also limit
the message severity level that will be accepted by the channel
(the default is <command>info</command>), and whether to include
a <command>named</command>-generated time stamp, the category name
and/or severity level (the default is not to include any).</para>
<para>The word <command>null</command> as the destination option
for the channel will cause all messages sent to it to be discarded;
in that case, other options for the channel are meaningless.</para>
<para>The <command>file</command> clause can include limitations
both on how large the file is allowed to become, and how many versions
of the file will be saved each time the file is opened.</para>
<para>The <command>size</command> option for files is simply a hard
ceiling on log growth. If the file ever exceeds the size, then <command>named</command> will
not write anything more to it until the file is reopened; exceeding
the size does not automatically trigger a reopen. The default behavior
is not to limit the size of the file.</para>
<para>If you use the <command>version</command> log file option,
then <command>named</command> will retain that many backup versions
of the file by renaming them when opening. For example, if you choose
to keep 3 old versions of the file <filename>lamers.log</filename> then
just before it is opened <filename>lamers.log.1</filename> is renamed
to <filename>lamers.log.2</filename>, <filename>lamers.log.0</filename> is
renamed to <filename>lamers.log.1</filename>, and <filename>lamers.log</filename> is
renamed to <filename>lamers.log.0</filename>. No rolled versions
are kept by default; any existing log file is simply appended. The <command>unlimited</command> keyword
is synonymous with <command>99</command> in current <acronym>BIND</acronym> releases.</para>
<para>Example usage of the size and versions options:</para>
        <programlisting>channel "an_example_channel" {
    file "example.log" versions 3 size 20m;
    print-time yes;
    print-category yes;
};
        </programlisting>
<para>The argument for the <command>syslog</command> clause is a
syslog facility as described in the <command>syslog</command> man
page. How <command>syslog</command> will handle messages sent to
this facility is described in the <command>syslog.conf</command> man
page. If you have a system which uses a very old version of <command>syslog</command> that
only uses two arguments to the <command>openlog()</command> function,
then this clause is silently ignored.</para>
<para>The <command>severity</command> clause works like <command>syslog</command>'s
"priorities," except that they can also be used if you are writing
straight to a file rather than using <command>syslog</command>.
Messages which are not at least of the severity level given will
not be selected for the channel; messages of higher severity levels
will be accepted.</para>
<para>If you are using <command>syslog</command>, then the <command>syslog.conf</command> priorities
will also determine what eventually passes through. For example,
defining a channel facility and severity as <command>daemon</command> and <command>debug</command> but
only logging <command>daemon.warning</command> via <command>syslog.conf</command> will
cause messages of severity <command>info</command> and <command>notice</command> to
be dropped. If the situation were reversed, with <command>named</command> writing
messages of only <command>warning</command> or higher, then <command>syslogd</command> would
print all messages it received from the channel.</para>
<para>The server can supply extensive debugging information when
it is in debugging mode. If the server's global debug level is greater
than zero, then debugging mode will be active. The global debug
level is set either by starting the <command>named</command> server
with the <option>-d</option> flag followed by a positive integer,
or by running <command>rndc trace</command>. <note>
            <simpara>the latter
method is not yet implemented</simpara></note> The global debug level
can be set to zero, and debugging mode turned off, by running <command>ndc
notrace</command>. All debugging messages in the server have a debug
level, and higher debug levels give more detailed output. Channels
that specify a specific debug severity, for example:</para>
<programlisting>channel "specific_debug_level" {
    file "foo";
    severity debug 3;
};
</programlisting>
        <para>will get debugging output of level 3 or less any time the
server is in debugging mode, regardless of the global debugging
level. Channels with <command>dynamic</command> severity use the
server's global level to determine what messages to print.</para>
        <para>If <command>print-time</command> has been turned on, then
the date and time will be logged. <command>print-time</command> may
be specified for a <command>syslog</command> channel, but is usually
pointless since <command>syslog</command> also prints the date and
time. If <command>print-category</command> is requested, then the
category of the message will be logged as well. Finally, if <command>print-severity</command> is
on, then the severity level of the message will be logged. The <command>print-</command> options may
be used in any combination, and will always be printed in the following
order: time, category, severity. Here is an example where all three <command>print-</command> options
are on:</para>
        <para><computeroutput>28-Feb-2000 15:05:32.863 general: notice: running</computeroutput></para>
        <para>There are four predefined channels that are used for
<command>named</command>'s default logging as follows. How they are
used is described in <xref linkend="the_category_phrase"/>.
</para>
        <programlisting>channel "default_syslog" {
    syslog daemon;			// end to syslog's daemon
					// facility
    severity info;			// only send priority info
					// and higher
};
channel "default_debug" {
    file "named.run";			// write to named.run in
					// the working directory
					// Note: stderr is used instead
					// of "named.run"
					// if the server is started
					// with the '-f' option.
    severity dynamic			// log at the server's
					// current debug level
};
channel "default_stderr" {		// writes to stderr
    file "&lt;stderr&gt;";			// this is illustrative only;
					// there's currently no way of
					// specifying an internal file
					// descriptor in the 
					// configuration language.
    severity info;			// only send priority info
					// and higher
};
channel "null" {
   null;				// toss anything sent to
					// this channel
};
</programlisting>
<para>The <command>default_debug</command> channel normally writes
to a file <filename>named.run</filename> in the server's working
directory.  For security reasons, when the "<option>-u</option>"
command line option is used, the <filename>named.run</filename> file
is created only after <command>named</command> has changed to the
new UID, and any debug output generated while <command>named</command> is
starting up and still running as root is discarded.  If you need
to capture this output, you must run the server with the "<option>-g</option>"
option and redirect standard error to a file.</para>
<para>Once a channel is defined, it cannot be redefined. Thus you
cannot alter the built-in channels directly, but you can modify
the default logging by pointing categories at channels you have defined.</para></sect3>
<sect3 id="the_category_phrase"><title>The <command>category</command> Phrase</title>
<para>There are many categories, so you can send the logs you want
to see wherever you want, without seeing logs you don't want. If
you don't specify a list of channels for a category, then log messages
in that category will be sent to the <command>default</command> category
instead. If you don't specify a default category, the following
"default default" is used:</para>
<programlisting>category "default" { "default_syslog"; "default_debug"; };
</programlisting>
<para>As an example, let's say you want to log security events to
a file, but you also want keep the default logging behavior. You'd
specify the following:</para>
<programlisting>channel "my_security_channel" {
    file "my_security_file";
    severity info;
};
category "security" {
    "my_security_channel";
    "default_syslog";
    "default_debug";
};</programlisting>
<para>To discard all messages in a category, specify the <command>null</command> channel:</para>
<programlisting>category "xfer-out" { "null"; };
category "notify" { "null"; };
</programlisting>
<para>Following are the available categories and brief descriptions
of the types of log information they contain. More
categories may be added in future <acronym>BIND</acronym> releases.</para>
<informaltable
    colsep = "0" rowsep = "0"><tgroup cols = "2"
    colsep = "0" rowsep = "0" tgroupstyle = "4Level-table">
<colspec colname = "1" colnum = "1" colsep = "0" colwidth = "1.150in"/>
<colspec colname = "2" colnum = "2" colsep = "0" colwidth = "3.350in"/>
<tbody>
<row rowsep = "0">
<entry colname = "1"><para><command>default</command></para></entry>
<entry colname = "2"><para>The default category defines the logging
options for those categories where no specific configuration has been
defined.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>general</command></para></entry>
<entry colname = "2"><para>The catch-all. Many things still aren't
classified into categories, and they all end up here.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>database</command></para></entry>
<entry colname = "2"><para>Messages relating to the databases used
internally by the name server to store zone and cache data.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>security</command></para></entry>
<entry colname = "2"><para>Approval and denial of requests.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>config</command></para></entry>
<entry colname = "2"><para>Configuration file parsing and processing.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>resolver</command></para></entry>
<entry colname = "2"><para>DNS resolution, such as the recursive
lookups performed on behalf of clients by a caching name server.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>xfer-in</command></para></entry>
<entry colname = "2"><para>Zone transfers the server is receiving.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>xfer-out</command></para></entry>
<entry colname = "2"><para>Zone transfers the server is sending.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>notify</command></para></entry>
<entry colname = "2"><para>The NOTIFY protocol.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>client</command></para></entry>
<entry colname = "2"><para>Processing of client requests.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>network</command></para></entry>
<entry colname = "2"><para>Network operations.</para></entry>
</row>
<row rowsep = "0">
<entry colname = "1"><para><command>update</command></para></entry>
<entry colname = "2"><para>Dynamic updates.</para></entry>
</row>
</tbody>
</tgroup></informaltable>
      </sect3>
    </sect2>
    <sect2>
      <title><command>options</command> Statement Grammar</title>

2341
      <para>This is the grammar of the <command>options</command>
2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367
      statement in the <filename>named.conf</filename> file:</para>
<programlisting><command>options</command> {
    <optional> version <replaceable>version_string</replaceable>; </optional>
    <optional> directory <replaceable>path_name</replaceable>; </optional>
    <optional> named-xfer <replaceable>path_name</replaceable>; </optional>
    <optional> tkey-domain <replaceable>domainname</replaceable>; </optional>
    <optional> tkey-dhkey <replaceable>key_name</replaceable> <replaceable>key_tag</replaceable>; </optional>
    <optional> dump-file <replaceable>path_name</replaceable>; </optional>
    <optional> memstatistics-file <replaceable>path_name</replaceable>; </optional>
    <optional> pid-file <replaceable>path_name</replaceable>; </optional>
    <optional> statistics-file <replaceable>path_name</replaceable>; </optional>
    <optional> auth-nxdomain <replaceable>yes_or_no</replaceable>; </optional>
    <optional> deallocate-on-exit <replaceable>yes_or_no</replaceable>; </optional>
    <optional> dialup <replaceable>yes_or_no</replaceable>; </optional>
    <optional> fake-iquery <replaceable>yes_or_no</replaceable>; </optional>
    <optional> fetch-glue <replaceable>yes_or_no</replaceable>; </optional>
    <optional> has-old-clients <replaceable>yes_or_no</replaceable>; </optional>
    <optional> host-statistics <replaceable>yes_or_no</replaceable>; </optional>
    <optional> multiple-cnames <replaceable>yes_or_no</replaceable>; </optional>
    <optional> notify <replaceable>yes_or_no</replaceable>; </optional>
    <optional> recursion <replaceable>yes_or_no</replaceable>; </optional>
    <optional> rfc2308-type1 <replaceable>yes_or_no</replaceable>; </optional>
    <optional> use-id-pool <replaceable>yes_or_no</replaceable>; </optional>
    <optional> maintain-ixfr-base <replaceable>yes_or_no</replaceable>; </optional>
    <optional> forward ( <replaceable>only</replaceable> | <replaceable>first</replaceable> ); </optional>
    <optional> forwarders { <optional> <replaceable>in_addr</replaceable> ; <optional> <replaceable>in_addr</replaceable> ; ... </optional> </optional> }; </optional>
2368
    <optional> check-names ( <replaceable>master</replaceable> | <replaceable>slave</replaceable> | <replaceable> response</replaceable> )( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464