PageRenderTime 213ms CodeModel.GetById 31ms app.highlight 109ms RepoModel.GetById 1ms app.codeStats 3ms

/contrib/bind9/doc/arm/Bv9ARM-book.xml

https://bitbucket.org/freebsd/freebsd-head/
XML | 12029 lines | 11175 code | 821 blank | 33 comment | 0 complexity | 229a224015246795a39e20aab94ec4c8 MD5 | raw file
    1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    2              "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
    3	       [<!ENTITY mdash "&#8212;">]>
    4<!--
    5 - Copyright (C) 2004-2012  Internet Systems Consortium, Inc. ("ISC")
    6 - Copyright (C) 2000-2003  Internet Software Consortium.
    7 -
    8 - Permission to use, copy, modify, and/or distribute this software for any
    9 - purpose with or without fee is hereby granted, provided that the above
   10 - copyright notice and this permission notice appear in all copies.
   11 -
   12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
   14 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
   15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
   16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
   17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
   18 - PERFORMANCE OF THIS SOFTWARE.
   19-->
   20
   21<!-- File: $Id$ -->
   22<book xmlns:xi="http://www.w3.org/2001/XInclude">
   23  <title>BIND 9 Administrator Reference Manual</title>
   24
   25  <bookinfo>
   26    <copyright>
   27      <year>2004</year>
   28      <year>2005</year>
   29      <year>2006</year>
   30      <year>2007</year>
   31      <year>2008</year>
   32      <year>2009</year>
   33      <year>2010</year>
   34      <year>2011</year>
   35      <year>2012</year>
   36      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
   37    </copyright>
   38    <copyright>
   39      <year>2000</year>
   40      <year>2001</year>
   41      <year>2002</year>
   42      <year>2003</year>
   43      <holder>Internet Software Consortium.</holder>
   44    </copyright>
   45  </bookinfo>
   46
   47  <chapter id="Bv9ARM.ch01">
   48    <title>Introduction</title>
   49    <para>
   50      The Internet Domain Name System (<acronym>DNS</acronym>)
   51      consists of the syntax
   52      to specify the names of entities in the Internet in a hierarchical
   53      manner, the rules used for delegating authority over names, and the
   54      system implementation that actually maps names to Internet
   55      addresses.  <acronym>DNS</acronym> data is maintained in a
   56      group of distributed
   57      hierarchical databases.
   58    </para>
   59
   60    <sect1>
   61      <title>Scope of Document</title>
   62
   63      <para>
   64        The Berkeley Internet Name Domain
   65        (<acronym>BIND</acronym>) implements a
   66        domain name server for a number of operating systems. This
   67        document provides basic information about the installation and
   68        care of the Internet Systems Consortium (<acronym>ISC</acronym>)
   69        <acronym>BIND</acronym> version 9 software package for
   70        system administrators.
   71      </para>
   72
   73      <para>
   74        This version of the manual corresponds to BIND version 9.8.
   75      </para>
   76
   77    </sect1>
   78    <sect1>
   79      <title>Organization of This Document</title>
   80      <para>
   81        In this document, <emphasis>Chapter 1</emphasis> introduces
   82        the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Chapter 2</emphasis>
   83        describes resource requirements for running <acronym>BIND</acronym> in various
   84        environments. Information in <emphasis>Chapter 3</emphasis> is
   85        <emphasis>task-oriented</emphasis> in its presentation and is
   86        organized functionally, to aid in the process of installing the
   87        <acronym>BIND</acronym> 9 software. The task-oriented
   88        section is followed by
   89        <emphasis>Chapter 4</emphasis>, which contains more advanced
   90        concepts that the system administrator may need for implementing
   91        certain options. <emphasis>Chapter 5</emphasis>
   92        describes the <acronym>BIND</acronym> 9 lightweight
   93        resolver.  The contents of <emphasis>Chapter 6</emphasis> are
   94        organized as in a reference manual to aid in the ongoing
   95        maintenance of the software. <emphasis>Chapter 7</emphasis> addresses
   96        security considerations, and
   97        <emphasis>Chapter 8</emphasis> contains troubleshooting help. The
   98        main body of the document is followed by several
   99        <emphasis>appendices</emphasis> which contain useful reference
  100        information, such as a <emphasis>bibliography</emphasis> and
  101        historic information related to <acronym>BIND</acronym>
  102        and the Domain Name
  103        System.
  104      </para>
  105    </sect1>
  106    <sect1>
  107      <title>Conventions Used in This Document</title>
  108
  109      <para>
  110        In this document, we use the following general typographic
  111        conventions:
  112      </para>
  113
  114      <informaltable>
  115        <tgroup cols="2">
  116          <colspec colname="1" colnum="1" colwidth="3.000in"/>
  117          <colspec colname="2" colnum="2" colwidth="2.625in"/>
  118          <tbody>
  119            <row>
  120              <entry colname="1">
  121                <para>
  122                  <emphasis>To describe:</emphasis>
  123                </para>
  124              </entry>
  125              <entry colname="2">
  126                <para>
  127                  <emphasis>We use the style:</emphasis>
  128                </para>
  129              </entry>
  130            </row>
  131            <row>
  132              <entry colname="1">
  133                <para>
  134                  a pathname, filename, URL, hostname,
  135                  mailing list name, or new term or concept
  136                </para>
  137              </entry>
  138              <entry colname="2">
  139                <para>
  140                  <filename>Fixed width</filename>
  141                </para>
  142              </entry>
  143            </row>
  144            <row>
  145              <entry colname="1">
  146                <para>
  147                  literal user
  148                  input
  149                </para>
  150              </entry>
  151              <entry colname="2">
  152                <para>
  153                  <userinput>Fixed Width Bold</userinput>
  154                </para>
  155              </entry>
  156            </row>
  157            <row>
  158              <entry colname="1">
  159                <para>
  160                  program output
  161                </para>
  162              </entry>
  163              <entry colname="2">
  164                <para>
  165                  <computeroutput>Fixed Width</computeroutput>
  166                </para>
  167              </entry>
  168            </row>
  169          </tbody>
  170        </tgroup>
  171      </informaltable>
  172
  173      <para>
  174        The following conventions are used in descriptions of the
  175        <acronym>BIND</acronym> configuration file:<informaltable colsep="0" frame="all" rowsep="0">
  176                  <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
  177                      <colspec colname="1" colnum="1" colsep="0" colwidth="3.000in"/>
  178            <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/>
  179            <tbody>
  180              <row rowsep="0">
  181                <entry colname="1" colsep="1" rowsep="1">
  182                  <para>
  183                    <emphasis>To describe:</emphasis>
  184                  </para>
  185                </entry>
  186                <entry colname="2" rowsep="1">
  187                  <para>
  188                    <emphasis>We use the style:</emphasis>
  189                  </para>
  190                </entry>
  191              </row>
  192              <row rowsep="0">
  193                <entry colname="1" colsep="1" rowsep="1">
  194                  <para>
  195                    keywords
  196                  </para>
  197                </entry>
  198                <entry colname="2" rowsep="1">
  199                  <para>
  200                    <literal>Fixed Width</literal>
  201                  </para>
  202                </entry>
  203              </row>
  204              <row rowsep="0">
  205                <entry colname="1" colsep="1" rowsep="1">
  206                  <para>
  207                    variables
  208                  </para>
  209                </entry>
  210                <entry colname="2" rowsep="1">
  211                  <para>
  212                    <varname>Fixed Width</varname>
  213                  </para>
  214                </entry>
  215              </row>
  216              <row rowsep="0">
  217                <entry colname="1" colsep="1">
  218                  <para>
  219                    Optional input
  220                  </para>
  221                </entry>
  222                <entry colname="2">
  223                  <para>
  224                    <optional>Text is enclosed in square brackets</optional>
  225                  </para>
  226                </entry>
  227              </row>
  228            </tbody>
  229          </tgroup>
  230        </informaltable>
  231      </para>
  232    </sect1>
  233    <sect1>
  234      <title>The Domain Name System (<acronym>DNS</acronym>)</title>
  235      <para>
  236        The purpose of this document is to explain the installation
  237        and upkeep of the <acronym>BIND</acronym> (Berkeley Internet
  238	Name Domain) software package, and we
  239        begin by reviewing the fundamentals of the Domain Name System
  240        (<acronym>DNS</acronym>) as they relate to <acronym>BIND</acronym>.
  241      </para>
  242
  243      <sect2>
  244        <title>DNS Fundamentals</title>
  245
  246        <para>
  247          The Domain Name System (DNS) is a hierarchical, distributed
  248          database.  It stores information for mapping Internet host names to
  249          IP
  250          addresses and vice versa, mail routing information, and other data
  251          used by Internet applications.
  252        </para>
  253
  254        <para>
  255          Clients look up information in the DNS by calling a
  256          <emphasis>resolver</emphasis> library, which sends queries to one or
  257          more <emphasis>name servers</emphasis> and interprets the responses.
  258          The <acronym>BIND</acronym> 9 software distribution
  259          contains a
  260          name server, <command>named</command>, and a resolver
  261          library, <command>liblwres</command>.  The older
  262          <command>libbind</command> resolver library is also available
  263          from ISC as a separate download.
  264        </para>
  265
  266        </sect2><sect2>
  267        <title>Domains and Domain Names</title>
  268
  269        <para>
  270          The data stored in the DNS is identified by <emphasis>domain names</emphasis> that are organized as a tree according to
  271          organizational or administrative boundaries. Each node of the tree,
  272          called a <emphasis>domain</emphasis>, is given a label. The domain
  273          name of the
  274          node is the concatenation of all the labels on the path from the
  275          node to the <emphasis>root</emphasis> node.  This is represented
  276          in written form as a string of labels listed from right to left and
  277          separated by dots. A label need only be unique within its parent
  278          domain.
  279        </para>
  280
  281        <para>
  282          For example, a domain name for a host at the
  283          company <emphasis>Example, Inc.</emphasis> could be
  284          <literal>ourhost.example.com</literal>,
  285          where <literal>com</literal> is the
  286          top level domain to which
  287          <literal>ourhost.example.com</literal> belongs,
  288          <literal>example</literal> is
  289          a subdomain of <literal>com</literal>, and
  290          <literal>ourhost</literal> is the
  291          name of the host.
  292        </para>
  293
  294        <para>
  295          For administrative purposes, the name space is partitioned into
  296          areas called <emphasis>zones</emphasis>, each starting at a node and
  297          extending down to the leaf nodes or to nodes where other zones
  298          start.
  299          The data for each zone is stored in a <emphasis>name server</emphasis>, which answers queries about the zone using the
  300          <emphasis>DNS protocol</emphasis>.
  301        </para>
  302
  303        <para>
  304          The data associated with each domain name is stored in the
  305          form of <emphasis>resource records</emphasis> (<acronym>RR</acronym>s).
  306          Some of the supported resource record types are described in
  307          <xref linkend="types_of_resource_records_and_when_to_use_them"/>.
  308        </para>
  309
  310        <para>
  311          For more detailed information about the design of the DNS and
  312          the DNS protocol, please refer to the standards documents listed in
  313          <xref linkend="rfcs"/>.
  314        </para>
  315      </sect2>
  316
  317      <sect2>
  318        <title>Zones</title>
  319        <para>
  320          To properly operate a name server, it is important to understand
  321          the difference between a <emphasis>zone</emphasis>
  322          and a <emphasis>domain</emphasis>.
  323        </para>
  324
  325        <para>
  326          As stated previously, a zone is a point of delegation in
  327          the <acronym>DNS</acronym> tree. A zone consists of
  328          those contiguous parts of the domain
  329          tree for which a name server has complete information and over which
  330          it has authority. It contains all domain names from a certain point
  331          downward in the domain tree except those which are delegated to
  332          other zones. A delegation point is marked by one or more
  333          <emphasis>NS records</emphasis> in the
  334          parent zone, which should be matched by equivalent NS records at
  335          the root of the delegated zone.
  336        </para>
  337
  338        <para>
  339          For instance, consider the <literal>example.com</literal>
  340          domain which includes names
  341          such as <literal>host.aaa.example.com</literal> and
  342          <literal>host.bbb.example.com</literal> even though
  343          the <literal>example.com</literal> zone includes
  344          only delegations for the <literal>aaa.example.com</literal> and
  345          <literal>bbb.example.com</literal> zones.  A zone can
  346          map
  347          exactly to a single domain, but could also include only part of a
  348          domain, the rest of which could be delegated to other
  349          name servers. Every name in the <acronym>DNS</acronym>
  350          tree is a
  351          <emphasis>domain</emphasis>, even if it is
  352          <emphasis>terminal</emphasis>, that is, has no
  353          <emphasis>subdomains</emphasis>.  Every subdomain is a domain and
  354          every domain except the root is also a subdomain. The terminology is
  355          not intuitive and we suggest that you read RFCs 1033, 1034 and 1035
  356          to
  357          gain a complete understanding of this difficult and subtle
  358          topic.
  359        </para>
  360
  361        <para>
  362          Though <acronym>BIND</acronym> is called a "domain name
  363          server",
  364          it deals primarily in terms of zones. The master and slave
  365          declarations in the <filename>named.conf</filename> file
  366          specify
  367          zones, not domains. When you ask some other site if it is willing to
  368          be a slave server for your <emphasis>domain</emphasis>, you are
  369          actually asking for slave service for some collection of zones.
  370        </para>
  371      </sect2>
  372
  373      <sect2>
  374        <title>Authoritative Name Servers</title>
  375
  376        <para>
  377          Each zone is served by at least
  378          one <emphasis>authoritative name server</emphasis>,
  379          which contains the complete data for the zone.
  380          To make the DNS tolerant of server and network failures,
  381          most zones have two or more authoritative servers, on
  382          different networks.
  383        </para>
  384
  385        <para>
  386          Responses from authoritative servers have the "authoritative
  387          answer" (AA) bit set in the response packets.  This makes them
  388          easy to identify when debugging DNS configurations using tools like
  389          <command>dig</command> (<xref linkend="diagnostic_tools"/>).
  390        </para>
  391
  392        <sect3>
  393          <title>The Primary Master</title>
  394
  395          <para>
  396            The authoritative server where the master copy of the zone
  397            data is maintained is called the
  398	    <emphasis>primary master</emphasis> server, or simply the
  399            <emphasis>primary</emphasis>.  Typically it loads the zone
  400            contents from some local file edited by humans or perhaps
  401            generated mechanically from some other local file which is
  402            edited by humans.  This file is called the
  403	    <emphasis>zone file</emphasis> or
  404	    <emphasis>master file</emphasis>.
  405          </para>
  406
  407	  <para>
  408	    In some cases, however, the master file may not be edited
  409	    by humans at all, but may instead be the result of
  410	    <emphasis>dynamic update</emphasis> operations.
  411	  </para>
  412        </sect3>
  413
  414        <sect3>
  415          <title>Slave Servers</title>
  416          <para>
  417            The other authoritative servers, the <emphasis>slave</emphasis>
  418            servers (also known as <emphasis>secondary</emphasis> servers)
  419            load
  420            the zone contents from another server using a replication process
  421            known as a <emphasis>zone transfer</emphasis>.  Typically the data
  422            are
  423            transferred directly from the primary master, but it is also
  424            possible
  425            to transfer it from another slave.  In other words, a slave server
  426            may itself act as a master to a subordinate slave server.
  427          </para>
  428        </sect3>
  429
  430        <sect3>
  431          <title>Stealth Servers</title>
  432
  433          <para>
  434            Usually all of the zone's authoritative servers are listed in
  435            NS records in the parent zone.  These NS records constitute
  436            a <emphasis>delegation</emphasis> of the zone from the parent.
  437            The authoritative servers are also listed in the zone file itself,
  438            at the <emphasis>top level</emphasis> or <emphasis>apex</emphasis>
  439            of the zone.  You can list servers in the zone's top-level NS
  440            records that are not in the parent's NS delegation, but you cannot
  441            list servers in the parent's delegation that are not present at
  442            the zone's top level.
  443          </para>
  444
  445          <para>
  446            A <emphasis>stealth server</emphasis> is a server that is
  447            authoritative for a zone but is not listed in that zone's NS
  448            records.  Stealth servers can be used for keeping a local copy of
  449            a
  450            zone to speed up access to the zone's records or to make sure that
  451            the
  452            zone is available even if all the "official" servers for the zone
  453            are
  454            inaccessible.
  455          </para>
  456
  457          <para>
  458            A configuration where the primary master server itself is a
  459            stealth server is often referred to as a "hidden primary"
  460            configuration.  One use for this configuration is when the primary
  461            master
  462            is behind a firewall and therefore unable to communicate directly
  463            with the outside world.
  464          </para>
  465
  466        </sect3>
  467
  468      </sect2>
  469      <sect2>
  470
  471        <title>Caching Name Servers</title>
  472
  473	<!--
  474	  - Terminology here is inconsistent.  Probably ought to
  475	  - convert to using "recursive name server" everywhere
  476	  - with just a note about "caching" terminology.
  477	  -->
  478
  479        <para>
  480          The resolver libraries provided by most operating systems are
  481          <emphasis>stub resolvers</emphasis>, meaning that they are not
  482          capable of
  483          performing the full DNS resolution process by themselves by talking
  484          directly to the authoritative servers.  Instead, they rely on a
  485          local
  486          name server to perform the resolution on their behalf.  Such a
  487          server
  488          is called a <emphasis>recursive</emphasis> name server; it performs
  489          <emphasis>recursive lookups</emphasis> for local clients.
  490        </para>
  491
  492        <para>
  493          To improve performance, recursive servers cache the results of
  494          the lookups they perform.  Since the processes of recursion and
  495          caching are intimately connected, the terms
  496          <emphasis>recursive server</emphasis> and
  497          <emphasis>caching server</emphasis> are often used synonymously.
  498        </para>
  499
  500        <para>
  501          The length of time for which a record may be retained in
  502          the cache of a caching name server is controlled by the
  503          Time To Live (TTL) field associated with each resource record.
  504        </para>
  505
  506        <sect3>
  507          <title>Forwarding</title>
  508
  509          <para>
  510            Even a caching name server does not necessarily perform
  511            the complete recursive lookup itself.  Instead, it can
  512            <emphasis>forward</emphasis> some or all of the queries
  513            that it cannot satisfy from its cache to another caching name
  514            server,
  515            commonly referred to as a <emphasis>forwarder</emphasis>.
  516          </para>
  517
  518          <para>
  519            There may be one or more forwarders,
  520            and they are queried in turn until the list is exhausted or an
  521            answer
  522            is found. Forwarders are typically used when you do not
  523            wish all the servers at a given site to interact directly with the
  524            rest of
  525            the Internet servers. A typical scenario would involve a number
  526            of internal <acronym>DNS</acronym> servers and an
  527            Internet firewall. Servers unable
  528            to pass packets through the firewall would forward to the server
  529            that can do it, and that server would query the Internet <acronym>DNS</acronym> servers
  530            on the internal server's behalf.
  531          </para>
  532        </sect3>
  533
  534      </sect2>
  535
  536      <sect2>
  537        <title>Name Servers in Multiple Roles</title>
  538
  539        <para>
  540          The <acronym>BIND</acronym> name server can
  541          simultaneously act as
  542          a master for some zones, a slave for other zones, and as a caching
  543          (recursive) server for a set of local clients.
  544        </para>
  545
  546        <para>
  547          However, since the functions of authoritative name service
  548          and caching/recursive name service are logically separate, it is
  549          often advantageous to run them on separate server machines.
  550
  551          A server that only provides authoritative name service
  552          (an <emphasis>authoritative-only</emphasis> server) can run with
  553          recursion disabled, improving reliability and security.
  554
  555          A server that is not authoritative for any zones and only provides
  556          recursive service to local
  557          clients (a <emphasis>caching-only</emphasis> server)
  558          does not need to be reachable from the Internet at large and can
  559          be placed inside a firewall.
  560        </para>
  561
  562      </sect2>
  563    </sect1>
  564
  565  </chapter>
  566
  567  <chapter id="Bv9ARM.ch02">
  568    <title><acronym>BIND</acronym> Resource Requirements</title>
  569
  570    <sect1>
  571      <title>Hardware requirements</title>
  572
  573      <para>
  574        <acronym>DNS</acronym> hardware requirements have
  575        traditionally been quite modest.
  576        For many installations, servers that have been pensioned off from
  577        active duty have performed admirably as <acronym>DNS</acronym> servers.
  578      </para>
  579      <para>
  580        The DNSSEC features of <acronym>BIND</acronym> 9
  581        may prove to be quite
  582        CPU intensive however, so organizations that make heavy use of these
  583        features may wish to consider larger systems for these applications.
  584        <acronym>BIND</acronym> 9 is fully multithreaded, allowing
  585        full utilization of
  586        multiprocessor systems for installations that need it.
  587      </para>
  588    </sect1>
  589    <sect1>
  590      <title>CPU Requirements</title>
  591      <para>
  592        CPU requirements for <acronym>BIND</acronym> 9 range from
  593        i486-class machines
  594        for serving of static zones without caching, to enterprise-class
  595        machines if you intend to process many dynamic updates and DNSSEC
  596        signed zones, serving many thousands of queries per second.
  597      </para>
  598    </sect1>
  599
  600    <sect1>
  601      <title>Memory Requirements</title>
  602      <para>
  603        The memory of the server has to be large enough to fit the
  604        cache and zones loaded off disk.  The <command>max-cache-size</command>
  605        option can be used to limit the amount of memory used by the cache,
  606        at the expense of reducing cache hit rates and causing more <acronym>DNS</acronym>
  607        traffic.
  608        Additionally, if additional section caching
  609        (<xref linkend="acache"/>) is enabled,
  610        the <command>max-acache-size</command> option can be used to
  611        limit the amount
  612        of memory used by the mechanism.
  613        It is still good practice to have enough memory to load
  614        all zone and cache data into memory &mdash; unfortunately, the best
  615        way
  616        to determine this for a given installation is to watch the name server
  617        in operation. After a few weeks the server process should reach
  618        a relatively stable size where entries are expiring from the cache as
  619        fast as they are being inserted.
  620      </para>
  621      <!--
  622        - Add something here about leaving overhead for attacks?
  623	- How much overhead?  Percentage?
  624        -->
  625    </sect1>
  626
  627    <sect1>
  628      <title>Name Server Intensive Environment Issues</title>
  629      <para>
  630        For name server intensive environments, there are two alternative
  631        configurations that may be used. The first is where clients and
  632        any second-level internal name servers query a main name server, which
  633        has enough memory to build a large cache. This approach minimizes
  634        the bandwidth used by external name lookups. The second alternative
  635        is to set up second-level internal name servers to make queries
  636        independently.
  637        In this configuration, none of the individual machines needs to
  638        have as much memory or CPU power as in the first alternative, but
  639        this has the disadvantage of making many more external queries,
  640        as none of the name servers share their cached data.
  641      </para>
  642    </sect1>
  643
  644    <sect1>
  645      <title>Supported Operating Systems</title>
  646      <para>
  647        ISC <acronym>BIND</acronym> 9 compiles and runs on a large
  648        number
  649        of Unix-like operating systems and on 
  650        Microsoft Windows Server 2003 and 2008, and Windows XP and Vista.
  651        For an up-to-date
  652        list of supported systems, see the README file in the top level
  653        directory
  654        of the BIND 9 source distribution.
  655      </para>
  656    </sect1>
  657  </chapter>
  658
  659  <chapter id="Bv9ARM.ch03">
  660    <title>Name Server Configuration</title>
  661    <para>
  662      In this chapter we provide some suggested configurations along
  663      with guidelines for their use.  We suggest reasonable values for
  664      certain option settings.
  665    </para>
  666
  667    <sect1 id="sample_configuration">
  668      <title>Sample Configurations</title>
  669      <sect2>
  670        <title>A Caching-only Name Server</title>
  671        <para>
  672          The following sample configuration is appropriate for a caching-only
  673          name server for use by clients internal to a corporation.  All
  674          queries
  675          from outside clients are refused using the <command>allow-query</command>
  676          option.  Alternatively, the same effect could be achieved using
  677          suitable
  678          firewall rules.
  679        </para>
  680
  681<programlisting>
  682// Two corporate subnets we wish to allow queries from.
  683acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
  684options {
  685     // Working directory
  686     directory "/etc/namedb";
  687
  688     allow-query { corpnets; };
  689};
  690// Provide a reverse mapping for the loopback
  691// address 127.0.0.1
  692zone "0.0.127.in-addr.arpa" {
  693     type master;
  694     file "localhost.rev";
  695     notify no;
  696};
  697</programlisting>
  698
  699      </sect2>
  700
  701      <sect2>
  702        <title>An Authoritative-only Name Server</title>
  703        <para>
  704          This sample configuration is for an authoritative-only server
  705          that is the master server for "<filename>example.com</filename>"
  706          and a slave for the subdomain "<filename>eng.example.com</filename>".
  707        </para>
  708
  709<programlisting>
  710options {
  711     // Working directory
  712     directory "/etc/namedb";
  713     // Do not allow access to cache
  714     allow-query-cache { none; };
  715     // This is the default
  716     allow-query { any; };
  717     // Do not provide recursive service
  718     recursion no;
  719};
  720
  721// Provide a reverse mapping for the loopback
  722// address 127.0.0.1
  723zone "0.0.127.in-addr.arpa" {
  724     type master;
  725     file "localhost.rev";
  726     notify no;
  727};
  728// We are the master server for example.com
  729zone "example.com" {
  730     type master;
  731     file "example.com.db";
  732     // IP addresses of slave servers allowed to
  733     // transfer example.com
  734     allow-transfer {
  735          192.168.4.14;
  736          192.168.5.53;
  737     };
  738};
  739// We are a slave server for eng.example.com
  740zone "eng.example.com" {
  741     type slave;
  742     file "eng.example.com.bk";
  743     // IP address of eng.example.com master server
  744     masters { 192.168.4.12; };
  745};
  746</programlisting>
  747
  748      </sect2>
  749    </sect1>
  750
  751    <sect1>
  752      <title>Load Balancing</title>
  753      <!--
  754        - Add explanation of why load balancing is fragile at best
  755	- and completely pointless in the general case.
  756        -->
  757
  758      <para>
  759        A primitive form of load balancing can be achieved in
  760        the <acronym>DNS</acronym> by using multiple records
  761	(such as multiple A records) for one name.
  762      </para>
  763
  764      <para>
  765        For example, if you have three WWW servers with network addresses
  766        of 10.0.0.1, 10.0.0.2 and 10.0.0.3, a set of records such as the
  767        following means that clients will connect to each machine one third
  768        of the time:
  769      </para>
  770
  771      <informaltable colsep="0" rowsep="0">
  772        <tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="2Level-table">
  773          <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/>
  774          <colspec colname="2" colnum="2" colsep="0" colwidth="0.500in"/>
  775          <colspec colname="3" colnum="3" colsep="0" colwidth="0.750in"/>
  776          <colspec colname="4" colnum="4" colsep="0" colwidth="0.750in"/>
  777          <colspec colname="5" colnum="5" colsep="0" colwidth="2.028in"/>
  778          <tbody>
  779            <row rowsep="0">
  780              <entry colname="1">
  781                <para>
  782                  Name
  783                </para>
  784              </entry>
  785              <entry colname="2">
  786                <para>
  787                  TTL
  788                </para>
  789              </entry>
  790              <entry colname="3">
  791                <para>
  792                  CLASS
  793                </para>
  794              </entry>
  795              <entry colname="4">
  796                <para>
  797                  TYPE
  798                </para>
  799              </entry>
  800              <entry colname="5">
  801                <para>
  802                  Resource Record (RR) Data
  803                </para>
  804              </entry>
  805            </row>
  806            <row rowsep="0">
  807              <entry colname="1">
  808                <para>
  809                  <literal>www</literal>
  810                </para>
  811              </entry>
  812              <entry colname="2">
  813                <para>
  814                  <literal>600</literal>
  815                </para>
  816              </entry>
  817              <entry colname="3">
  818                <para>
  819                  <literal>IN</literal>
  820                </para>
  821              </entry>
  822              <entry colname="4">
  823                <para>
  824                  <literal>A</literal>
  825                </para>
  826              </entry>
  827              <entry colname="5">
  828                <para>
  829                  <literal>10.0.0.1</literal>
  830                </para>
  831              </entry>
  832            </row>
  833            <row rowsep="0">
  834              <entry colname="1">
  835                <para/>
  836              </entry>
  837              <entry colname="2">
  838                <para>
  839                  <literal>600</literal>
  840                </para>
  841              </entry>
  842              <entry colname="3">
  843                <para>
  844                  <literal>IN</literal>
  845                </para>
  846              </entry>
  847              <entry colname="4">
  848                <para>
  849                  <literal>A</literal>
  850                </para>
  851              </entry>
  852              <entry colname="5">
  853                <para>
  854                  <literal>10.0.0.2</literal>
  855                </para>
  856              </entry>
  857            </row>
  858            <row rowsep="0">
  859              <entry colname="1">
  860                <para/>
  861              </entry>
  862              <entry colname="2">
  863                <para>
  864                  <literal>600</literal>
  865                </para>
  866              </entry>
  867              <entry colname="3">
  868                <para>
  869                  <literal>IN</literal>
  870                </para>
  871              </entry>
  872              <entry colname="4">
  873                <para>
  874                  <literal>A</literal>
  875                </para>
  876              </entry>
  877              <entry colname="5">
  878                <para>
  879                  <literal>10.0.0.3</literal>
  880                </para>
  881              </entry>
  882            </row>
  883          </tbody>
  884        </tgroup>
  885      </informaltable>
  886      <para>
  887        When a resolver queries for these records, <acronym>BIND</acronym> will rotate
  888        them and respond to the query with the records in a different
  889        order.  In the example above, clients will randomly receive
  890        records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients
  891        will use the first record returned and discard the rest.
  892      </para>
  893      <para>
  894        For more detail on ordering responses, check the
  895        <command>rrset-order</command> sub-statement in the
  896        <command>options</command> statement, see
  897        <xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>.
  898      </para>
  899
  900    </sect1>
  901
  902    <sect1>
  903      <title>Name Server Operations</title>
  904
  905      <sect2>
  906        <title>Tools for Use With the Name Server Daemon</title>
  907        <para>
  908          This section describes several indispensable diagnostic,
  909          administrative and monitoring tools available to the system
  910          administrator for controlling and debugging the name server
  911          daemon.
  912        </para>
  913        <sect3 id="diagnostic_tools">
  914          <title>Diagnostic Tools</title>
  915          <para>
  916            The <command>dig</command>, <command>host</command>, and
  917            <command>nslookup</command> programs are all command
  918            line tools
  919            for manually querying name servers.  They differ in style and
  920            output format.
  921          </para>
  922
  923          <variablelist>
  924            <varlistentry>
  925              <term id="dig"><command>dig</command></term>
  926              <listitem>
  927                <para>
  928                  The domain information groper (<command>dig</command>)
  929                  is the most versatile and complete of these lookup tools.
  930                  It has two modes: simple interactive
  931                  mode for a single query, and batch mode which executes a
  932                  query for
  933                  each in a list of several query lines. All query options are
  934                  accessible
  935                  from the command line.
  936                </para>
  937                <cmdsynopsis label="Usage">
  938                  <command>dig</command>
  939                  <arg>@<replaceable>server</replaceable></arg>
  940                  <arg choice="plain"><replaceable>domain</replaceable></arg>
  941                  <arg><replaceable>query-type</replaceable></arg>
  942                  <arg><replaceable>query-class</replaceable></arg>
  943                  <arg>+<replaceable>query-option</replaceable></arg>
  944                  <arg>-<replaceable>dig-option</replaceable></arg>
  945                  <arg>%<replaceable>comment</replaceable></arg>
  946                </cmdsynopsis>
  947                <para>
  948                  The usual simple use of <command>dig</command> will take the form
  949                </para>
  950                <simpara>
  951                  <command>dig @server domain query-type query-class</command>
  952                </simpara>
  953                <para>
  954                  For more information and a list of available commands and
  955                  options, see the <command>dig</command> man
  956                  page.
  957                </para>
  958              </listitem>
  959            </varlistentry>
  960
  961            <varlistentry>
  962              <term><command>host</command></term>
  963              <listitem>
  964                <para>
  965                  The <command>host</command> utility emphasizes
  966                  simplicity
  967                  and ease of use.  By default, it converts
  968                  between host names and Internet addresses, but its
  969                  functionality
  970                  can be extended with the use of options.
  971                </para>
  972                <cmdsynopsis label="Usage">
  973                  <command>host</command>
  974                  <arg>-aCdlnrsTwv</arg>
  975                  <arg>-c <replaceable>class</replaceable></arg>
  976                  <arg>-N <replaceable>ndots</replaceable></arg>
  977                  <arg>-t <replaceable>type</replaceable></arg>
  978                  <arg>-W <replaceable>timeout</replaceable></arg>
  979                  <arg>-R <replaceable>retries</replaceable></arg>
  980                  <arg>-m <replaceable>flag</replaceable></arg>
  981		  <arg>-4</arg>
  982		  <arg>-6</arg>
  983                  <arg choice="plain"><replaceable>hostname</replaceable></arg>
  984                  <arg><replaceable>server</replaceable></arg>
  985                </cmdsynopsis>
  986                <para>
  987                  For more information and a list of available commands and
  988                  options, see the <command>host</command> man
  989                  page.
  990                </para>
  991              </listitem>
  992            </varlistentry>
  993
  994            <varlistentry>
  995              <term><command>nslookup</command></term>
  996              <listitem>
  997                <para><command>nslookup</command>
  998		  has two modes: interactive and
  999                  non-interactive. Interactive mode allows the user to
 1000                  query name servers for information about various
 1001                  hosts and domains or to print a list of hosts in a
 1002                  domain. Non-interactive mode is used to print just
 1003                  the name and requested information for a host or
 1004                  domain.
 1005                </para>
 1006                <cmdsynopsis label="Usage">
 1007                  <command>nslookup</command>
 1008                  <arg rep="repeat">-option</arg>
 1009                  <group>
 1010                    <arg><replaceable>host-to-find</replaceable></arg>
 1011                    <arg>- <arg>server</arg></arg>
 1012                  </group>
 1013                </cmdsynopsis>
 1014                <para>
 1015                  Interactive mode is entered when no arguments are given (the
 1016                  default name server will be used) or when the first argument
 1017                  is a
 1018                  hyphen (`-') and the second argument is the host name or
 1019                  Internet address
 1020                  of a name server.
 1021                </para>
 1022                <para>
 1023                  Non-interactive mode is used when the name or Internet
 1024                  address
 1025                  of the host to be looked up is given as the first argument.
 1026                  The
 1027                  optional second argument specifies the host name or address
 1028                  of a name server.
 1029                </para>
 1030                <para>
 1031                  Due to its arcane user interface and frequently inconsistent
 1032                  behavior, we do not recommend the use of <command>nslookup</command>.
 1033                  Use <command>dig</command> instead.
 1034                </para>
 1035              </listitem>
 1036
 1037            </varlistentry>
 1038          </variablelist>
 1039        </sect3>
 1040
 1041        <sect3 id="admin_tools">
 1042          <title>Administrative Tools</title>
 1043          <para>
 1044            Administrative tools play an integral part in the management
 1045            of a server.
 1046          </para>
 1047          <variablelist>
 1048            <varlistentry id="named-checkconf" xreflabel="Named Configuration Checking application">
 1049
 1050              <term><command>named-checkconf</command></term>
 1051              <listitem>
 1052                <para>
 1053                  The <command>named-checkconf</command> program
 1054                  checks the syntax of a <filename>named.conf</filename> file.
 1055                </para>
 1056                <cmdsynopsis label="Usage">
 1057                  <command>named-checkconf</command>
 1058                  <arg>-jvz</arg>
 1059                  <arg>-t <replaceable>directory</replaceable></arg>
 1060                  <arg><replaceable>filename</replaceable></arg>
 1061                </cmdsynopsis>
 1062              </listitem>
 1063            </varlistentry>
 1064            <varlistentry id="named-checkzone" xreflabel="Zone Checking application">
 1065
 1066              <term><command>named-checkzone</command></term>
 1067              <listitem>
 1068                <para>
 1069                  The <command>named-checkzone</command> program
 1070                  checks a master file for
 1071                  syntax and consistency.
 1072                </para>
 1073                <cmdsynopsis label="Usage">
 1074                  <command>named-checkzone</command>
 1075                  <arg>-djqvD</arg>
 1076                  <arg>-c <replaceable>class</replaceable></arg>
 1077                  <arg>-o <replaceable>output</replaceable></arg>
 1078                  <arg>-t <replaceable>directory</replaceable></arg>
 1079                  <arg>-w <replaceable>directory</replaceable></arg>
 1080                  <arg>-k <replaceable>(ignore|warn|fail)</replaceable></arg>
 1081                  <arg>-n <replaceable>(ignore|warn|fail)</replaceable></arg>
 1082                  <arg>-W <replaceable>(ignore|warn)</replaceable></arg>
 1083                  <arg choice="plain"><replaceable>zone</replaceable></arg>
 1084                  <arg><replaceable>filename</replaceable></arg>
 1085                </cmdsynopsis>
 1086              </listitem>
 1087            </varlistentry>
 1088	    <varlistentry id="named-compilezone" xreflabel="Zone Compilation application">
 1089	      <term><command>named-compilezone</command></term>
 1090	      <listitem>
 1091		<para>
 1092		  Similar to <command>named-checkzone,</command> but
 1093		  it always dumps the zone content to a specified file
 1094		  (typically in a different format).
 1095		</para>
 1096	      </listitem>
 1097	    </varlistentry>
 1098            <varlistentry id="rndc" xreflabel="Remote Name Daemon Control application">
 1099
 1100              <term><command>rndc</command></term>
 1101              <listitem>
 1102                <para>
 1103                  The remote name daemon control
 1104                  (<command>rndc</command>) program allows the
 1105                  system
 1106                  administrator to control the operation of a name server.
 1107                  Since <acronym>BIND</acronym> 9.2, <command>rndc</command>
 1108                  supports all the commands of the BIND 8 <command>ndc</command>
 1109                  utility except <command>ndc start</command> and
 1110                  <command>ndc restart</command>, which were also
 1111                  not supported in <command>ndc</command>'s
 1112                  channel mode.
 1113                  If you run <command>rndc</command> without any
 1114                  options
 1115                  it will display a usage message as follows:
 1116                </para>
 1117                <cmdsynopsis label="Usage">
 1118                  <command>rndc</command>
 1119                  <arg>-c <replaceable>config</replaceable></arg>
 1120                  <arg>-s <replaceable>server</replaceable></arg>
 1121                  <arg>-p <replaceable>port</replaceable></arg>
 1122                  <arg>-y <replaceable>key</replaceable></arg>
 1123                  <arg choice="plain"><replaceable>command</replaceable></arg>
 1124                  <arg rep="repeat"><replaceable>command</replaceable></arg>
 1125                </cmdsynopsis>
 1126                <para>The <command>command</command>
 1127		  is one of the following:
 1128                </para>
 1129
 1130                <variablelist>
 1131
 1132                  <varlistentry>
 1133                    <term><userinput>reload</userinput></term>
 1134                    <listitem>
 1135                      <para>
 1136                        Reload configuration file and zones.
 1137                      </para>
 1138                    </listitem>
 1139                  </varlistentry>
 1140
 1141                  <varlistentry>
 1142                    <term><userinput>reload <replaceable>zone</replaceable>
 1143                        <optional><replaceable>class</replaceable>
 1144           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1145                    <listitem>
 1146                      <para>
 1147                        Reload the given zone.
 1148                      </para>
 1149                    </listitem>
 1150                  </varlistentry>
 1151
 1152                  <varlistentry>
 1153                    <term><userinput>refresh <replaceable>zone</replaceable>
 1154                        <optional><replaceable>class</replaceable>
 1155           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1156                    <listitem>
 1157                      <para>
 1158                        Schedule zone maintenance for the given zone.
 1159                      </para>
 1160                    </listitem>
 1161                  </varlistentry>
 1162
 1163                  <varlistentry>
 1164                    <term><userinput>retransfer <replaceable>zone</replaceable>
 1165
 1166                        <optional><replaceable>class</replaceable>
 1167           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1168                    <listitem>
 1169                      <para>
 1170                        Retransfer the given zone from the master.
 1171                      </para>
 1172                    </listitem>
 1173                  </varlistentry>
 1174
 1175                  <varlistentry>
 1176                    <term><userinput>sign <replaceable>zone</replaceable>
 1177                        <optional><replaceable>class</replaceable>
 1178           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1179                    <listitem>
 1180                      <para>
 1181                        Fetch all DNSSEC keys for the given zone
 1182                        from the key directory (see
 1183                        <command>key-directory</command> in
 1184                        <xref linkend="options"/>).  If they are within
 1185                        their publication period, merge them into the
 1186                        zone's DNSKEY RRset.  If the DNSKEY RRset
 1187                        is changed, then the zone is automatically
 1188                        re-signed with the new key set.
 1189                      </para>
 1190                      <para>
 1191                        This command requires that the
 1192                        <command>auto-dnssec</command> zone option be set
 1193                        to <literal>allow</literal> or
 1194                        <literal>maintain</literal>,
 1195                        and also requires the zone to be configured to
 1196                        allow dynamic DNS.
 1197                        See <xref linkend="dynamic_update_policies"/> for
 1198                        more details.
 1199                      </para>
 1200                    </listitem>
 1201                  </varlistentry>
 1202
 1203                  <varlistentry>
 1204                    <term><userinput>loadkeys <replaceable>zone</replaceable>
 1205                        <optional><replaceable>class</replaceable>
 1206           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1207                    <listitem>
 1208                      <para>
 1209                        Fetch all DNSSEC keys for the given zone
 1210                        from the key directory (see
 1211                        <command>key-directory</command> in
 1212                        <xref linkend="options"/>).  If they are within
 1213                        their publication period, merge them into the
 1214                        zone's DNSKEY RRset.  Unlike <command>rndc
 1215                        sign</command>, however, the zone is not
 1216                        immediately re-signed by the new keys, but is
 1217                        allowed to incrementally re-sign over time.
 1218                      </para>
 1219                      <para>
 1220                        This command requires that the
 1221                        <command>auto-dnssec</command> zone option
 1222                        be set to <literal>maintain</literal>,
 1223                        and also requires the zone to be configured to
 1224                        allow dynamic DNS.
 1225                        See <xref linkend="dynamic_update_policies"/> for
 1226                        more details.
 1227                      </para>
 1228                    </listitem>
 1229                  </varlistentry>
 1230
 1231                  <varlistentry>
 1232                    <term><userinput>freeze
 1233                        <optional><replaceable>zone</replaceable>
 1234       <optional><replaceable>class</replaceable>
 1235           <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term>
 1236                    <listitem>
 1237                      <para>
 1238                        Suspend updates to a dynamic zone.  If no zone is
 1239                        specified,
 1240                        then all zones are suspended.  This allows manual
 1241                        edits to be made to a zone normally updated by dynamic
 1242                        update.  It
 1243                        also causes changes in the journal file to be synced
 1244                        into the master
 1245                        and the journal file to be removed.  All dynamic
 1246                        update attempts will
 1247                        be refused while the zone is frozen.
 1248                      </para>
 1249                    </listitem>
 1250                  </varlistentry>
 1251
 1252                  <varlistentry>
 1253                    <term><userinput>thaw
 1254                        <optional><replaceable>zone</replaceable>
 1255       <optional><replaceable>class</replaceable>
 1256           <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term>
 1257                    <listitem>
 1258                      <para>
 1259                        Enable updates to a frozen dynamic zone.  If no zone
 1260                        is
 1261                        specified, then all frozen zones are enabled.  This
 1262                        causes
 1263                        the server to reload the zone from disk, and
 1264                        re-enables dynamic updates
 1265                        after the load has completed.  After a zone is thawed,
 1266                        dynamic updates
 1267                        will no longer be refused.
 1268                      </para>
 1269                    </listitem>
 1270                  </varlistentry>
 1271
 1272                  <varlistentry>
 1273                    <term><userinput>notify <replaceable>zone</replaceable>
 1274                        <optional><replaceable>class</replaceable>
 1275           <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 1276                    <listitem>
 1277                      <para>
 1278                        Resend NOTIFY messages for the zone.
 1279                      </para>
 1280                    </listitem>
 1281                  </varlistentry>
 1282
 1283                  <varlistentry>
 1284                    <term><userinput>reconfig</userinput></term>
 1285                    <listitem>
 1286                      <para>
 1287                        Reload the configuration file and load new zones,
 1288                        but do not reload existing zone files even if they
 1289                        have changed.
 1290                        This is faster than a full <command>reload</command> when there
 1291                        is a large number of zones because it avoids the need
 1292                        to examine the
 1293                        modification times of the zones files.
 1294                      </para>
 1295                    </listitem>
 1296                  </varlistentry>
 1297
 1298                  <varlistentry>
 1299                    <term><userinput>stats</userinput></term>
 1300                    <listitem>
 1301                      <para>
 1302                        Write server statistics to the statistics file.
 1303                      </para>
 1304                    </listitem>
 1305                  </varlistentry>
 1306
 1307                  <varlistentry>
 1308                    <term><userinput>querylog</userinput></term>
 1309                    <listitem>
 1310                      <para>
 1311                        Toggle query logging. Query logging can also be enabled
 1312                        by explicitly directing the <command>queries</command>
 1313                        <command>category</command> to a
 1314		        <command>channel</command> in the
 1315                        <command>logging</command> section of
 1316                        <filename>named.conf</filename> or by specifying
 1317			<command>querylog yes;</command> in the
 1318			<command>options</command> section of
 1319			<filename>named.conf</filename>.
 1320                      </para>
 1321                    </listitem>
 1322                  </varlistentry>
 1323
 1324                  <varlistentry>
 1325                    <term><userinput>dumpdb
 1326                        <optional>-all|-cache|-zone</optional>
 1327                        <optional><replaceable>view ...</replaceable></optional></userinput></term>
 1328                    <listitem>
 1329                      <para>
 1330                        Dump the server's caches (default) and/or zones to
 1331                        the
 1332                        dump file for the specified views.  If no view is
 1333                        specified, all
 1334                        views are dumped.
 1335                      </para>
 1336                    </listitem>
 1337                  </varlistentry>
 1338
 1339                  <varlistentry>
 1340                    <term><userinput>secroots
 1341                        <optional><replaceable>view ...</replaceable></optional></userinput></term>
 1342                    <listitem>
 1343                      <para>
 1344                        Dump the server's security roots to the secroots
 1345                        file for the specified views.  If no view is
 1346                        specified, security roots for all
 1347                        views are dumped.
 1348                      </para>
 1349                    </listitem>
 1350                  </varlistentry>
 1351
 1352                  <varlistentry>
 1353                    <term><userinput>stop <optional>-p</optional></userinput></term>
 1354                    <listitem>
 1355                      <para>
 1356                        Stop the server, making sure any recent changes
 1357                        made through dynamic update or IXFR are first saved to
 1358                        the master files of the updated zones.
 1359			If <option>-p</option> is specified <command>named</command>'s process id is returned.
 1360			This allows an external process to determine when <command>named</command>
 1361			had completed stopping.
 1362                      </para>
 1363                    </listitem>
 1364                  </varlistentry>
 1365
 1366                  <varlistentry>
 1367                    <term><userinput>halt <optional>-p</optional></userinput></term>
 1368                    <listitem>
 1369                      <para>
 1370                        Stop the server immediately.  Recent changes
 1371                        made through dynamic update or IXFR are not saved to
 1372                        the master files, but will be rolled forward from the
 1373			journal files when the server is restarted.
 1374			If <option>-p</option> is specified <command>named</command>'s process id is returned.
 1375			This allows an external process to determine when <command>named</command>
 1376			had completed halting.
 1377                      </para>
 1378                    </listitem>
 1379                  </varlistentry>
 1380
 1381                  <varlistentry>
 1382                    <term><userinput>trace</userinput></term>
 1383                    <listitem>
 1384                      <para>
 1385                        Increment the servers debugging level by one.
 1386                      </para>
 1387                    </listitem>
 1388                  </varlistentry>
 1389
 1390                  <varlistentry>
 1391                    <term><userinput>trace <replaceable>level</replaceable></userinput></term>
 1392                    <listitem>
 1393                      <para>
 1394                        Sets the server's debugging level to an explicit
 1395                        value.
 1396                      </para>
 1397                    </listitem>
 1398                  </varlistentry>
 1399
 1400                  <varlistentry>
 1401                    <term><userinput>notrace</userinput></term>
 1402                    <listitem>
 1403                      <para>
 1404                        Sets the server's debugging level to 0.
 1405                      </para>
 1406                    </listitem>
 1407                  </varlistentry>
 1408
 1409                  <varlistentry>
 1410                    <term><userinput>flush</userinput></term>
 1411                    <listitem>
 1412                      <para>
 1413                        Flushes the server's cache.
 1414                      </para>
 1415                    </listitem>
 1416                  </varlistentry>
 1417
 1418                  <varlistentry>
 1419                    <term><userinput>flushname</userinput> <replaceable>name</replaceable></term>
 1420                    <listitem>
 1421                      <para>
 1422                        Flushes the given name from the server's cache.
 1423                      </para>
 1424                    </listitem>
 1425                  </varlistentry>
 1426
 1427                  <varlistentry>
 1428                    <term><userinput>status</userinput></term>
 1429                    <listitem>
 1430                      <para>
 1431                        Display status of the server.
 1432                        Note that the number of zones includes the internal <command>bind/CH</command> zone
 1433                        and the default <command>./IN</command>
 1434                        hint zone if there is not an
 1435                        explicit root zone configured.
 1436                      </para>
 1437                    </listitem>
 1438                  </varlistentry>
 1439
 1440                  <varlistentry>
 1441                    <term><userinput>recursing</userinput></term>
 1442                    <listitem>
 1443                      <para>
 1444                        Dump the list of queries <command>named</command> is currently recursing
 1445                        on.
 1446                      </para>
 1447                    </listitem>
 1448                  </varlistentry>
 1449
 1450                  <varlistentry>
 1451                    <term><userinput>validation
 1452                        <optional>on|off</optional>
 1453                        <optional><replaceable>view ...</replaceable></optional>
 1454                    </userinput></term>
 1455                    <listitem>
 1456                      <para>
 1457                        Enable or disable DNSSEC validation.
 1458                        Note <command>dnssec-enable</command> also needs to be
 1459                        set to <userinput>yes</userinput> to be effective.
 1460                        It defaults to enabled.
 1461                      </para>
 1462                    </listitem>
 1463                  </varlistentry>
 1464
 1465                  <varlistentry>
 1466                    <term><userinput>tsig-list</userinput></term>
 1467                    <listitem>
 1468                      <para>
 1469                        List the names of all TSIG keys currently configured
 1470                        for use by <command>named</command> in each view.  The
 1471                        list both statically configured keys and dynamic
 1472                        TKEY-negotiated keys.
 1473                      </para>
 1474                    </listitem>
 1475                  </varlistentry>
 1476
 1477                  <varlistentry>
 1478                    <term><userinput>tsig-delete</userinput>
 1479                     <replaceable>keyname</replaceable>
 1480                     <optional><replaceable>view</replaceable></optional></term>
 1481                    <listitem>
 1482                      <para>
 1483                        Delete a given TKEY-negotated key from the server.
 1484                        (This does not apply to statically configured TSIG
 1485                        keys.)
 1486                      </para>
 1487                    </listitem>
 1488                  </varlistentry>
 1489
 1490                  <varlistentry>
 1491                    <term><userinput>addzone
 1492                        <replaceable>zone</replaceable>
 1493                        <optional><replaceable>class</replaceable>
 1494                        <optional><replaceable>view</replaceable></optional></optional>
 1495                        <replaceable>configuration</replaceable>
 1496                    </userinput></term>
 1497                    <listitem>
 1498                      <para>
 1499                        Add a zone while the server is running.  This
 1500                        command requires the
 1501                        <command>allow-new-zones</command> option to be set
 1502                        to <userinput>yes</userinput>.  The
 1503                        <replaceable>configuration</replaceable> string
 1504                        specified on the command line is the zone
 1505                        configuration text that would ordinarily be
 1506                        placed in <filename>named.conf</filename>.
 1507                      </para>
 1508                      <para>
 1509                        The configuration is saved in a file called
 1510                       <filename><replaceable>hash</replaceable>.nzf</filename>,
 1511                        where <replaceable>hash</replaceable> is a
 1512                        cryptographic hash generated from the name of
 1513                        the view.  When <command>named</command> is
 1514                        restarted, the file will be loaded into the view
 1515                        configuration, so that zones that were added
 1516                        can persist after a restart.
 1517                      </para>
 1518                      <para>
 1519                        This sample <command>addzone</command> command
 1520                        would add the zone <literal>example.com</literal>
 1521                        to the default view:
 1522                      </para>
 1523                      <para>
 1524<prompt>$ </prompt><userinput>rndc addzone example.com '{ type master; file "example.com.db"; };'</userinput>
 1525                      </para>
 1526                      <para>
 1527                        (Note the brackets and semi-colon around the zone
 1528                        configuration text.)
 1529                      </para>
 1530                    </listitem>
 1531                  </varlistentry>
 1532
 1533                  <varlistentry>
 1534                    <term><userinput>delzone
 1535                        <replaceable>zone</replaceable>
 1536                        <optional><replaceable>class</replaceable>
 1537                        <optional><replaceable>view</replaceable></optional></optional>
 1538                    </userinput></term>
 1539                    <listitem>
 1540                      <para>
 1541                        Delete a zone while the server is running.
 1542                        Only zones that were originally added via
 1543                        <command>rndc addzone</command> can be deleted
 1544                        in this matter.
 1545                      </para>
 1546                    </listitem>
 1547                  </varlistentry>
 1548
 1549                </variablelist>
 1550
 1551                <para>
 1552                  A configuration file is required, since all
 1553                  communication with the server is authenticated with
 1554                  digital signatures that rely on a shared secret, and
 1555                  there is no way to provide that secret other than with a
 1556                  configuration file.  The default location for the
 1557                  <command>rndc</command> configuration file is
 1558                  <filename>/etc/rndc.conf</filename>, but an
 1559                  alternate
 1560                  location can be specified with the <option>-c</option>
 1561                  option.  If the configuration file is not found,
 1562                  <command>rndc</command> will also look in
 1563                  <filename>/etc/rndc.key</filename> (or whatever
 1564                  <varname>sysconfdir</varname> was defined when
 1565                  the <acronym>BIND</acronym> build was
 1566                  configured).
 1567                  The <filename>rndc.key</filename> file is
 1568                  generated by
 1569                  running <command>rndc-confgen -a</command> as
 1570                  described in
 1571                  <xref linkend="controls_statement_definition_and_usage"/>.
 1572                </para>
 1573
 1574                <para>
 1575                  The format of the configuration file is similar to
 1576                  that of <filename>named.conf</filename>, but
 1577                  limited to
 1578                  only four statements, the <command>options</command>,
 1579                  <command>key</command>, <command>server</command> and
 1580                  <command>include</command>
 1581                  statements.  These statements are what associate the
 1582                  secret keys to the servers with which they are meant to
 1583                  be shared.  The order of statements is not
 1584                  significant.
 1585                </para>
 1586
 1587                <para>
 1588                  The <command>options</command> statement has
 1589                  three clauses:
 1590                  <command>default-server</command>, <command>default-key</command>,
 1591                  and <command>default-port</command>.
 1592                  <command>default-server</command> takes a
 1593                  host name or address argument  and represents the server
 1594                  that will
 1595                  be contacted if no <option>-s</option>
 1596                  option is provided on the command line.
 1597                  <command>default-key</command> takes
 1598                  the name of a key as its argument, as defined by a <command>key</command> statement.
 1599                  <command>default-port</command> specifies the
 1600                  port to which
 1601                  <command>rndc</command> should connect if no
 1602                  port is given on the command line or in a
 1603                  <command>server</command> statement.
 1604                </para>
 1605
 1606                <para>
 1607                  The <command>key</command> statement defines a
 1608                  key to be used
 1609                  by <command>rndc</command> when authenticating
 1610                  with
 1611                  <command>named</command>.  Its syntax is
 1612                  identical to the
 1613                  <command>key</command> statement in <filename>named.conf</filename>.
 1614                  The keyword <userinput>key</userinput> is
 1615                  followed by a key name, which must be a valid
 1616                  domain name, though it need not actually be hierarchical;
 1617                  thus,
 1618                  a string like "<userinput>rndc_key</userinput>" is a valid
 1619                  name.
 1620                  The <command>key</command> statement has two
 1621                  clauses:
 1622                  <command>algorithm</command> and <command>secret</command>.
 1623                  While the configuration parser will accept any string as the
 1624                  argument
 1625                  to algorithm, currently only the string "<userinput>hmac-md5</userinput>"
 1626                  has any meaning.  The secret is a base-64 encoded string
 1627		  as specified in RFC 3548.
 1628                </para>
 1629
 1630                <para>
 1631                  The <command>server</command> statement
 1632                  associates a key
 1633                  defined using the <command>key</command>
 1634                  statement with a server.
 1635                  The keyword <userinput>server</userinput> is followed by a
 1636                  host name or address.  The <command>server</command> statement
 1637                  has two clauses: <command>key</command> and <command>port</command>.
 1638                  The <command>key</command> clause specifies the
 1639                  name of the key
 1640                  to be used when communicating with this server, and the
 1641                  <command>port</command> clause can be used to
 1642                  specify the port <command>rndc</command> should
 1643                  connect
 1644                  to on the server.
 1645                </para>
 1646
 1647                <para>
 1648                  A sample minimal configuration file is as follows:
 1649                </para>
 1650
 1651<programlisting>
 1652key rndc_key {
 1653     algorithm "hmac-md5";
 1654     secret
 1655       "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
 1656};
 1657options {
 1658     default-server 127.0.0.1;
 1659     default-key    rndc_key;
 1660};
 1661</programlisting>
 1662
 1663                <para>
 1664                  This file, if installed as <filename>/etc/rndc.conf</filename>,
 1665                  would allow the command:
 1666                </para>
 1667
 1668                <para>
 1669                  <prompt>$ </prompt><userinput>rndc reload</userinput>
 1670                </para>
 1671
 1672                <para>
 1673                  to connect to 127.0.0.1 port 953 and cause the name server
 1674                  to reload, if a name server on the local machine were
 1675                  running with
 1676                  following controls statements:
 1677                </para>
 1678
 1679<programlisting>
 1680controls {
 1681        inet 127.0.0.1
 1682            allow { localhost; } keys { rndc_key; };
 1683};
 1684</programlisting>
 1685
 1686                <para>
 1687                  and it had an identical key statement for
 1688                  <literal>rndc_key</literal>.
 1689                </para>
 1690
 1691                <para>
 1692                  Running the <command>rndc-confgen</command>
 1693                  program will
 1694                  conveniently create a <filename>rndc.conf</filename>
 1695                  file for you, and also display the
 1696                  corresponding <command>controls</command>
 1697                  statement that you need to
 1698                  add to <filename>named.conf</filename>.
 1699                  Alternatively,
 1700                  you can run <command>rndc-confgen -a</command>
 1701                  to set up
 1702                  a <filename>rndc.key</filename> file and not
 1703                  modify
 1704                  <filename>named.conf</filename> at all.
 1705                </para>
 1706
 1707              </listitem>
 1708            </varlistentry>
 1709          </variablelist>
 1710
 1711        </sect3>
 1712      </sect2>
 1713      <sect2>
 1714
 1715        <title>Signals</title>
 1716        <para>
 1717          Certain UNIX signals cause the name server to take specific
 1718          actions, as described in the following table.  These signals can
 1719          be sent using the <command>kill</command> command.
 1720        </para>
 1721        <informaltable frame="all">
 1722          <tgroup cols="2">
 1723            <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/>
 1724            <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/>
 1725            <tbody>
 1726              <row rowsep="0">
 1727                <entry colname="1">
 1728                  <para><command>SIGHUP</command></para>
 1729                </entry>
 1730                <entry colname="2">
 1731                  <para>
 1732                    Causes the server to read <filename>named.conf</filename> and
 1733                    reload the database.
 1734                  </para>
 1735                </entry>
 1736              </row>
 1737              <row rowsep="0">
 1738                <entry colname="1">
 1739                  <para><command>SIGTERM</command></para>
 1740                </entry>
 1741                <entry colname="2">
 1742                  <para>
 1743                    Causes the server to clean up and exit.
 1744                  </para>
 1745                </entry>
 1746              </row>
 1747              <row rowsep="0">
 1748                <entry colname="1">
 1749                  <para><command>SIGINT</command></para>
 1750                </entry>
 1751                <entry colname="2">
 1752                  <para>
 1753                    Causes the server to clean up and exit.
 1754                  </para>
 1755                </entry>
 1756              </row>
 1757            </tbody>
 1758          </tgroup>
 1759        </informaltable>
 1760      </sect2>
 1761    </sect1>
 1762  </chapter>
 1763
 1764  <chapter id="Bv9ARM.ch04">
 1765    <title>Advanced DNS Features</title>
 1766
 1767    <sect1 id="notify">
 1768
 1769      <title>Notify</title>
 1770      <para>
 1771        <acronym>DNS</acronym> NOTIFY is a mechanism that allows master
 1772        servers to notify their slave servers of changes to a zone's data. In
 1773        response to a <command>NOTIFY</command> from a master server, the
 1774        slave will check to see that its version of the zone is the
 1775        current version and, if not, initiate a zone transfer.
 1776      </para>
 1777
 1778      <para>
 1779        For more information about <acronym>DNS</acronym>
 1780        <command>NOTIFY</command>, see the description of the
 1781        <command>notify</command> option in <xref linkend="boolean_options"/> and
 1782        the description of the zone option <command>also-notify</command> in
 1783        <xref linkend="zone_transfers"/>.  The <command>NOTIFY</command>
 1784        protocol is specified in RFC 1996.
 1785      </para>
 1786
 1787      <note>
 1788	As a slave zone can also be a master to other slaves, <command>named</command>,
 1789        by default, sends <command>NOTIFY</command> messages for every zone
 1790	it loads.  Specifying <command>notify master-only;</command> will
 1791	cause <command>named</command> to only send <command>NOTIFY</command> for master
 1792	zones that it loads.
 1793      </note>
 1794
 1795    </sect1>
 1796
 1797    <sect1 id="dynamic_update">
 1798      <title>Dynamic Update</title>
 1799
 1800      <para>
 1801        Dynamic Update is a method for adding, replacing or deleting
 1802        records in a master server by sending it a special form of DNS
 1803        messages.  The format and meaning of these messages is specified
 1804        in RFC 2136.
 1805      </para>
 1806
 1807      <para>
 1808	Dynamic update is enabled by including an
 1809	<command>allow-update</command> or an <command>update-policy</command>
 1810	clause in the <command>zone</command> statement.
 1811      </para>
 1812      
 1813      <para>
 1814	If the zone's <command>update-policy</command> is set to
 1815	<userinput>local</userinput>, updates to the zone
 1816	will be permitted for the key <varname>local-ddns</varname>,
 1817        which will be generated by <command>named</command> at startup.
 1818	See <xref linkend="dynamic_update_policies"/> for more details.
 1819      </para>
 1820
 1821      <para>
 1822	Dynamic updates using Kerberos signed requests can be made
 1823	using the TKEY/GSS protocol by setting either the
 1824	<command>tkey-gssapi-keytab</command> option, or alternatively
 1825	by setting both the <command>tkey-gssapi-credential</command>
 1826	and <command>tkey-domain</command> options. Once enabled,
 1827	Kerberos signed requests will be matched against the update
 1828	policies for the zone, using the Kerberos principal as the
 1829	signer for the request.
 1830      </para>
 1831
 1832      <para>
 1833	Updating of secure zones (zones using DNSSEC) follows RFC
 1834	3007: RRSIG, NSEC and NSEC3 records affected by updates are
 1835	automatically regenerated by the server using an online
 1836	zone key.  Update authorization is based on transaction
 1837	signatures and an explicit server policy.
 1838      </para>
 1839
 1840      <sect2 id="journal">
 1841	<title>The journal file</title>
 1842
 1843        <para>
 1844          All changes made to a zone using dynamic update are stored
 1845          in the zone's journal file.  This file is automatically created
 1846          by the server when the first dynamic update takes place.
 1847          The name of the journal file is formed by appending the extension
 1848          <filename>.jnl</filename> to the name of the
 1849          corresponding zone
 1850          file unless specifically overridden.  The journal file is in a
 1851          binary format and should not be edited manually.
 1852        </para>
 1853
 1854        <para>
 1855          The server will also occasionally write ("dump")
 1856          the complete contents of the updated zone to its zone file.
 1857          This is not done immediately after
 1858          each dynamic update, because that would be too slow when a large
 1859          zone is updated frequently.  Instead, the dump is delayed by
 1860          up to 15 minutes, allowing additional updates to take place.
 1861          During the dump process, transient files will be created
 1862          with the extensions <filename>.jnw</filename> and
 1863          <filename>.jbk</filename>; under ordinary circumstances, these
 1864          will be removed when the dump is complete, and can be safely
 1865          ignored.
 1866        </para>
 1867
 1868        <para>
 1869          When a server is restarted after a shutdown or crash, it will replay
 1870              the journal file to incorporate into the zone any updates that
 1871          took
 1872          place after the last zone dump.
 1873        </para>
 1874
 1875        <para>
 1876          Changes that result from incoming incremental zone transfers are
 1877          also
 1878          journalled in a similar way.
 1879        </para>
 1880
 1881        <para>
 1882          The zone files of dynamic zones cannot normally be edited by
 1883          hand because they are not guaranteed to contain the most recent
 1884          dynamic changes &mdash; those are only in the journal file.
 1885          The only way to ensure that the zone file of a dynamic zone
 1886          is up to date is to run <command>rndc stop</command>.
 1887        </para>
 1888
 1889        <para>
 1890          If you have to make changes to a dynamic zone
 1891          manually, the following procedure will work: Disable dynamic updates
 1892              to the zone using
 1893          <command>rndc freeze <replaceable>zone</replaceable></command>.
 1894          This will also remove the zone's <filename>.jnl</filename> file
 1895          and update the master file.  Edit the zone file.  Run
 1896          <command>rndc thaw <replaceable>zone</replaceable></command>
 1897          to reload the changed zone and re-enable dynamic updates.
 1898        </para>
 1899
 1900      </sect2>
 1901
 1902    </sect1>
 1903
 1904    <sect1 id="incremental_zone_transfers">
 1905      <title>Incremental Zone Transfers (IXFR)</title>
 1906
 1907      <para>
 1908        The incremental zone transfer (IXFR) protocol is a way for
 1909        slave servers to transfer only changed data, instead of having to
 1910        transfer the entire zone. The IXFR protocol is specified in RFC
 1911        1995. See <xref linkend="proposed_standards"/>.
 1912      </para>
 1913
 1914      <para>
 1915        When acting as a master, <acronym>BIND</acronym> 9
 1916        supports IXFR for those zones
 1917        where the necessary change history information is available. These
 1918        include master zones maintained by dynamic update and slave zones
 1919        whose data was obtained by IXFR.  For manually maintained master
 1920        zones, and for slave zones obtained by performing a full zone
 1921        transfer (AXFR), IXFR is supported only if the option
 1922        <command>ixfr-from-differences</command> is set
 1923        to <userinput>yes</userinput>.
 1924      </para>
 1925
 1926      <para>
 1927        When acting as a slave, <acronym>BIND</acronym> 9 will attempt
 1928        to use IXFR unless it is explicitly disabled via the
 1929        <command>request-ixfr</command> option or the use of
 1930        <command>ixfr-from-differences</command>.  For
 1931        more information about disabling IXFR, see the description
 1932        of the <command>request-ixfr</command> clause of the
 1933        <command>server</command> statement.
 1934      </para>
 1935    </sect1>
 1936
 1937    <sect1>
 1938      <title>Split DNS</title>
 1939      <para>
 1940        Setting up different views, or visibility, of the DNS space to
 1941        internal and external resolvers is usually referred to as a
 1942	<emphasis>Split DNS</emphasis> setup. There are several
 1943        reasons an organization would want to set up its DNS this way.
 1944      </para>
 1945      <para>
 1946        One common reason for setting up a DNS system this way is
 1947        to hide "internal" DNS information from "external" clients on the
 1948        Internet. There is some debate as to whether or not this is actually
 1949        useful.
 1950        Internal DNS information leaks out in many ways (via email headers,
 1951        for example) and most savvy "attackers" can find the information
 1952        they need using other means.
 1953	However, since listing addresses of internal servers that
 1954        external clients cannot possibly reach can result in
 1955        connection delays and other annoyances, an organization may
 1956        choose to use a Split DNS to present a consistent view of itself
 1957        to the outside world.
 1958      </para>
 1959      <para>
 1960        Another common reason for setting up a Split DNS system is
 1961        to allow internal networks that are behind filters or in RFC 1918
 1962        space (reserved IP space, as documented in RFC 1918) to resolve DNS
 1963        on the Internet. Split DNS can also be used to allow mail from outside
 1964        back in to the internal network.
 1965      </para>
 1966     <sect2>
 1967      <title>Example split DNS setup</title>
 1968      <para>
 1969        Let's say a company named <emphasis>Example, Inc.</emphasis>
 1970        (<literal>example.com</literal>)
 1971        has several corporate sites that have an internal network with
 1972        reserved
 1973        Internet Protocol (IP) space and an external demilitarized zone (DMZ),
 1974        or "outside" section of a network, that is available to the public.
 1975      </para>
 1976      <para>
 1977        <emphasis>Example, Inc.</emphasis> wants its internal clients
 1978        to be able to resolve external hostnames and to exchange mail with
 1979        people on the outside. The company also wants its internal resolvers
 1980        to have access to certain internal-only zones that are not available
 1981        at all outside of the internal network.
 1982      </para>
 1983      <para>
 1984        In order to accomplish this, the company will set up two sets
 1985        of name servers. One set will be on the inside network (in the
 1986        reserved
 1987        IP space) and the other set will be on bastion hosts, which are
 1988        "proxy"
 1989        hosts that can talk to both sides of its network, in the DMZ.
 1990      </para>
 1991      <para>
 1992        The internal servers will be configured to forward all queries,
 1993        except queries for <filename>site1.internal</filename>, <filename>site2.internal</filename>, <filename>site1.example.com</filename>,
 1994        and <filename>site2.example.com</filename>, to the servers
 1995        in the
 1996        DMZ. These internal servers will have complete sets of information
 1997        for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>, <filename>site1.internal</filename>,
 1998        and <filename>site2.internal</filename>.
 1999      </para>
 2000      <para>
 2001        To protect the <filename>site1.internal</filename> and <filename>site2.internal</filename> domains,
 2002        the internal name servers must be configured to disallow all queries
 2003        to these domains from any external hosts, including the bastion
 2004        hosts.
 2005      </para>
 2006      <para>
 2007        The external servers, which are on the bastion hosts, will
 2008        be configured to serve the "public" version of the <filename>site1</filename> and <filename>site2.example.com</filename> zones.
 2009        This could include things such as the host records for public servers
 2010        (<filename>www.example.com</filename> and <filename>ftp.example.com</filename>),
 2011        and mail exchange (MX)  records (<filename>a.mx.example.com</filename> and <filename>b.mx.example.com</filename>).
 2012      </para>
 2013      <para>
 2014        In addition, the public <filename>site1</filename> and <filename>site2.example.com</filename> zones
 2015        should have special MX records that contain wildcard (`*') records
 2016        pointing to the bastion hosts. This is needed because external mail
 2017        servers do not have any other way of looking up how to deliver mail
 2018        to those internal hosts. With the wildcard records, the mail will
 2019        be delivered to the bastion host, which can then forward it on to
 2020        internal hosts.
 2021      </para>
 2022      <para>
 2023        Here's an example of a wildcard MX record:
 2024      </para>
 2025      <programlisting>*   IN MX 10 external1.example.com.</programlisting>
 2026      <para>
 2027        Now that they accept mail on behalf of anything in the internal
 2028        network, the bastion hosts will need to know how to deliver mail
 2029        to internal hosts. In order for this to work properly, the resolvers
 2030        on
 2031        the bastion hosts will need to be configured to point to the internal
 2032        name servers for DNS resolution.
 2033      </para>
 2034      <para>
 2035        Queries for internal hostnames will be answered by the internal
 2036        servers, and queries for external hostnames will be forwarded back
 2037        out to the DNS servers on the bastion hosts.
 2038      </para>
 2039      <para>
 2040        In order for all this to work properly, internal clients will
 2041        need to be configured to query <emphasis>only</emphasis> the internal
 2042        name servers for DNS queries. This could also be enforced via
 2043        selective
 2044        filtering on the network.
 2045      </para>
 2046      <para>
 2047        If everything has been set properly, <emphasis>Example, Inc.</emphasis>'s
 2048        internal clients will now be able to:
 2049      </para>
 2050      <itemizedlist>
 2051        <listitem>
 2052          <simpara>
 2053            Look up any hostnames in the <literal>site1</literal>
 2054            and
 2055            <literal>site2.example.com</literal> zones.
 2056          </simpara>
 2057        </listitem>
 2058        <listitem>
 2059          <simpara>
 2060            Look up any hostnames in the <literal>site1.internal</literal> and
 2061            <literal>site2.internal</literal> domains.
 2062          </simpara>
 2063        </listitem>
 2064        <listitem>
 2065          <simpara>Look up any hostnames on the Internet.</simpara>
 2066        </listitem>
 2067        <listitem>
 2068          <simpara>Exchange mail with both internal and external people.</simpara>
 2069        </listitem>
 2070      </itemizedlist>
 2071      <para>
 2072        Hosts on the Internet will be able to:
 2073      </para>
 2074      <itemizedlist>
 2075        <listitem>
 2076          <simpara>
 2077            Look up any hostnames in the <literal>site1</literal>
 2078            and
 2079            <literal>site2.example.com</literal> zones.
 2080          </simpara>
 2081        </listitem>
 2082        <listitem>
 2083          <simpara>
 2084            Exchange mail with anyone in the <literal>site1</literal> and
 2085            <literal>site2.example.com</literal> zones.
 2086          </simpara>
 2087        </listitem>
 2088      </itemizedlist>
 2089
 2090      <para>
 2091        Here is an example configuration for the setup we just
 2092        described above. Note that this is only configuration information;
 2093        for information on how to configure your zone files, see <xref linkend="sample_configuration"/>.
 2094      </para>
 2095
 2096      <para>
 2097        Internal DNS server config:
 2098      </para>
 2099
 2100<programlisting>
 2101
 2102acl internals { 172.16.72.0/24; 192.168.1.0/24; };
 2103
 2104acl externals { <varname>bastion-ips-go-here</varname>; };
 2105
 2106options {
 2107    ...
 2108    ...
 2109    forward only;
 2110    // forward to external servers
 2111    forwarders {
 2112        <varname>bastion-ips-go-here</varname>;
 2113    };
 2114    // sample allow-transfer (no one)
 2115    allow-transfer { none; };
 2116    // restrict query access
 2117    allow-query { internals; externals; };
 2118    // restrict recursion
 2119    allow-recursion { internals; };
 2120    ...
 2121    ...
 2122};
 2123
 2124// sample master zone
 2125zone "site1.example.com" {
 2126  type master;
 2127  file "m/site1.example.com";
 2128  // do normal iterative resolution (do not forward)
 2129  forwarders { };
 2130  allow-query { internals; externals; };
 2131  allow-transfer { internals; };
 2132};
 2133
 2134// sample slave zone
 2135zone "site2.example.com" {
 2136  type slave;
 2137  file "s/site2.example.com";
 2138  masters { 172.16.72.3; };
 2139  forwarders { };
 2140  allow-query { internals; externals; };
 2141  allow-transfer { internals; };
 2142};
 2143
 2144zone "site1.internal" {
 2145  type master;
 2146  file "m/site1.internal";
 2147  forwarders { };
 2148  allow-query { internals; };
 2149  allow-transfer { internals; }
 2150};
 2151
 2152zone "site2.internal" {
 2153  type slave;
 2154  file "s/site2.internal";
 2155  masters { 172.16.72.3; };
 2156  forwarders { };
 2157  allow-query { internals };
 2158  allow-transfer { internals; }
 2159};
 2160</programlisting>
 2161
 2162      <para>
 2163        External (bastion host) DNS server config:
 2164      </para>
 2165
 2166<programlisting>
 2167acl internals { 172.16.72.0/24; 192.168.1.0/24; };
 2168
 2169acl externals { bastion-ips-go-here; };
 2170
 2171options {
 2172  ...
 2173  ...
 2174  // sample allow-transfer (no one)
 2175  allow-transfer { none; };
 2176  // default query access
 2177  allow-query { any; };
 2178  // restrict cache access
 2179  allow-query-cache { internals; externals; };
 2180  // restrict recursion
 2181  allow-recursion { internals; externals; };
 2182  ...
 2183  ...
 2184};
 2185
 2186// sample slave zone
 2187zone "site1.example.com" {
 2188  type master;
 2189  file "m/site1.foo.com";
 2190  allow-transfer { internals; externals; };
 2191};
 2192
 2193zone "site2.example.com" {
 2194  type slave;
 2195  file "s/site2.foo.com";
 2196  masters { another_bastion_host_maybe; };
 2197  allow-transfer { internals; externals; }
 2198};
 2199</programlisting>
 2200
 2201      <para>
 2202        In the <filename>resolv.conf</filename> (or equivalent) on
 2203        the bastion host(s):
 2204      </para>
 2205
 2206<programlisting>
 2207search ...
 2208nameserver 172.16.72.2
 2209nameserver 172.16.72.3
 2210nameserver 172.16.72.4
 2211</programlisting>
 2212
 2213     </sect2>
 2214    </sect1>
 2215    <sect1 id="tsig">
 2216      <title>TSIG</title>
 2217      <para>
 2218        This is a short guide to setting up Transaction SIGnatures
 2219        (TSIG) based transaction security in <acronym>BIND</acronym>. It describes changes
 2220        to the configuration file as well as what changes are required for
 2221        different features, including the process of creating transaction
 2222        keys and using transaction signatures with <acronym>BIND</acronym>.
 2223      </para>
 2224      <para>
 2225        <acronym>BIND</acronym> primarily supports TSIG for server
 2226        to server communication.
 2227        This includes zone transfer, notify, and recursive query messages.
 2228        Resolvers based on newer versions of <acronym>BIND</acronym> 8 have limited support
 2229        for TSIG.
 2230      </para>
 2231
 2232      <para>
 2233        TSIG can also be useful for dynamic update. A primary
 2234        server for a dynamic zone should control access to the dynamic
 2235        update service, but IP-based access control is insufficient.
 2236        The cryptographic access control provided by TSIG
 2237        is far superior. The <command>nsupdate</command>
 2238        program supports TSIG via the <option>-k</option> and
 2239        <option>-y</option> command line options or inline by use
 2240	of the <command>key</command>.
 2241      </para>
 2242
 2243      <sect2>
 2244        <title>Generate Shared Keys for Each Pair of Hosts</title>
 2245        <para>
 2246          A shared secret is generated to be shared between <emphasis>host1</emphasis> and <emphasis>host2</emphasis>.
 2247          An arbitrary key name is chosen: "host1-host2.". The key name must
 2248          be the same on both hosts.
 2249        </para>
 2250        <sect3>
 2251          <title>Automatic Generation</title>
 2252          <para>
 2253            The following command will generate a 128-bit (16 byte) HMAC-SHA256
 2254            key as described above. Longer keys are better, but shorter keys
 2255            are easier to read. Note that the maximum key length is the digest
 2256            length, here 256 bits.
 2257          </para>
 2258          <para>
 2259            <userinput>dnssec-keygen -a hmac-sha256 -b 128 -n HOST host1-host2.</userinput>
 2260          </para>
 2261          <para>
 2262            The key is in the file <filename>Khost1-host2.+163+00000.private</filename>.
 2263            Nothing directly uses this file, but the base-64 encoded string
 2264            following "<literal>Key:</literal>"
 2265            can be extracted from the file and used as a shared secret:
 2266          </para>
 2267          <programlisting>Key: La/E5CjG9O+os1jq0a2jdA==</programlisting>
 2268          <para>
 2269            The string "<literal>La/E5CjG9O+os1jq0a2jdA==</literal>" can
 2270            be used as the shared secret.
 2271          </para>
 2272        </sect3>
 2273        <sect3>
 2274          <title>Manual Generation</title>
 2275          <para>
 2276            The shared secret is simply a random sequence of bits, encoded
 2277            in base-64. Most ASCII strings are valid base-64 strings (assuming
 2278            the length is a multiple of 4 and only valid characters are used),
 2279            so the shared secret can be manually generated.
 2280          </para>
 2281          <para>
 2282            Also, a known string can be run through <command>mmencode</command> or
 2283            a similar program to generate base-64 encoded data.
 2284          </para>
 2285        </sect3>
 2286      </sect2>
 2287      <sect2>
 2288        <title>Copying the Shared Secret to Both Machines</title>
 2289        <para>
 2290          This is beyond the scope of DNS. A secure transport mechanism
 2291          should be used. This could be secure FTP, ssh, telephone, etc.
 2292        </para>
 2293      </sect2>
 2294      <sect2>
 2295        <title>Informing the Servers of the Key's Existence</title>
 2296        <para>
 2297          Imagine <emphasis>host1</emphasis> and <emphasis>host 2</emphasis>
 2298          are
 2299          both servers. The following is added to each server's <filename>named.conf</filename> file:
 2300        </para>
 2301
 2302<programlisting>
 2303key host1-host2. {
 2304  algorithm hmac-sha256;
 2305  secret "La/E5CjG9O+os1jq0a2jdA==";
 2306};
 2307</programlisting>
 2308
 2309        <para>
 2310          The secret is the one generated above. Since this is a secret, it
 2311          is recommended that either <filename>named.conf</filename> be
 2312          non-world readable, or the key directive be added to a non-world
 2313          readable file that is included by <filename>named.conf</filename>.
 2314        </para>
 2315        <para>
 2316          At this point, the key is recognized. This means that if the
 2317          server receives a message signed by this key, it can verify the
 2318          signature. If the signature is successfully verified, the
 2319          response is signed by the same key.
 2320        </para>
 2321      </sect2>
 2322
 2323      <sect2>
 2324        <title>Instructing the Server to Use the Key</title>
 2325        <para>
 2326          Since keys are shared between two hosts only, the server must
 2327          be told when keys are to be used. The following is added to the <filename>named.conf</filename> file
 2328          for <emphasis>host1</emphasis>, if the IP address of <emphasis>host2</emphasis> is
 2329          10.1.2.3:
 2330        </para>
 2331
 2332<programlisting>
 2333server 10.1.2.3 {
 2334  keys { host1-host2. ;};
 2335};
 2336</programlisting>
 2337
 2338        <para>
 2339          Multiple keys may be present, but only the first is used.
 2340          This directive does not contain any secrets, so it may be in a
 2341          world-readable
 2342          file.
 2343        </para>
 2344        <para>
 2345          If <emphasis>host1</emphasis> sends a message that is a request
 2346          to that address, the message will be signed with the specified key. <emphasis>host1</emphasis> will
 2347          expect any responses to signed messages to be signed with the same
 2348          key.
 2349        </para>
 2350        <para>
 2351          A similar statement must be present in <emphasis>host2</emphasis>'s
 2352          configuration file (with <emphasis>host1</emphasis>'s address) for <emphasis>host2</emphasis> to
 2353          sign request messages to <emphasis>host1</emphasis>.
 2354        </para>
 2355      </sect2>
 2356      <sect2>
 2357        <title>TSIG Key Based Access Control</title>
 2358        <para>
 2359          <acronym>BIND</acronym> allows IP addresses and ranges
 2360          to be specified in ACL
 2361          definitions and
 2362          <command>allow-{ query | transfer | update }</command>
 2363          directives.
 2364          This has been extended to allow TSIG keys also. The above key would
 2365          be denoted <command>key host1-host2.</command>
 2366        </para>
 2367        <para>
 2368          An example of an <command>allow-update</command> directive would be:
 2369        </para>
 2370
 2371<programlisting>
 2372allow-update { key host1-host2. ;};
 2373</programlisting>
 2374
 2375	<para>
 2376	  This allows dynamic updates to succeed only if the request
 2377	  was signed by a key named "<command>host1-host2.</command>".
 2378	</para>
 2379
 2380	<para>
 2381	  See <xref linkend="dynamic_update_policies"/> for a discussion of
 2382          the more flexible <command>update-policy</command> statement.
 2383	</para>
 2384
 2385      </sect2>
 2386      <sect2>
 2387        <title>Errors</title>
 2388
 2389        <para>
 2390          The processing of TSIG signed messages can result in
 2391          several errors. If a signed message is sent to a non-TSIG aware
 2392          server, a FORMERR (format error) will be returned, since the server will not
 2393          understand the record. This is a result of misconfiguration,
 2394          since the server must be explicitly configured to send a TSIG
 2395          signed message to a specific server.
 2396        </para>
 2397
 2398        <para>
 2399          If a TSIG aware server receives a message signed by an
 2400          unknown key, the response will be unsigned with the TSIG
 2401          extended error code set to BADKEY. If a TSIG aware server
 2402          receives a message with a signature that does not validate, the
 2403          response will be unsigned with the TSIG extended error code set
 2404          to BADSIG. If a TSIG aware server receives a message with a time
 2405          outside of the allowed range, the response will be signed with
 2406          the TSIG extended error code set to BADTIME, and the time values
 2407          will be adjusted so that the response can be successfully
 2408          verified. In any of these cases, the message's rcode (response code) is set to
 2409          NOTAUTH (not authenticated).
 2410        </para>
 2411
 2412      </sect2>
 2413    </sect1>
 2414    <sect1>
 2415      <title>TKEY</title>
 2416
 2417      <para><command>TKEY</command>
 2418        is a mechanism for automatically generating a shared secret
 2419        between two hosts.  There are several "modes" of
 2420        <command>TKEY</command> that specify how the key is generated
 2421        or assigned.  <acronym>BIND</acronym> 9 implements only one of
 2422        these modes, the Diffie-Hellman key exchange.  Both hosts are
 2423        required to have a Diffie-Hellman KEY record (although this
 2424        record is not required to be present in a zone).  The
 2425        <command>TKEY</command> process must use signed messages,
 2426        signed either by TSIG or SIG(0).  The result of
 2427        <command>TKEY</command> is a shared secret that can be used to
 2428        sign messages with TSIG.  <command>TKEY</command> can also be
 2429        used to delete shared secrets that it had previously
 2430        generated.
 2431      </para>
 2432
 2433      <para>
 2434        The <command>TKEY</command> process is initiated by a
 2435        client
 2436        or server by sending a signed <command>TKEY</command>
 2437        query
 2438        (including any appropriate KEYs) to a TKEY-aware server.  The
 2439        server response, if it indicates success, will contain a
 2440        <command>TKEY</command> record and any appropriate keys.
 2441        After
 2442        this exchange, both participants have enough information to
 2443        determine the shared secret; the exact process depends on the
 2444        <command>TKEY</command> mode.  When using the
 2445        Diffie-Hellman
 2446        <command>TKEY</command> mode, Diffie-Hellman keys are
 2447        exchanged,
 2448        and the shared secret is derived by both participants.
 2449      </para>
 2450
 2451    </sect1>
 2452    <sect1>
 2453      <title>SIG(0)</title>
 2454
 2455      <para>
 2456        <acronym>BIND</acronym> 9 partially supports DNSSEC SIG(0)
 2457            transaction signatures as specified in RFC 2535 and RFC 2931.
 2458        SIG(0)
 2459        uses public/private keys to authenticate messages.  Access control
 2460        is performed in the same manner as TSIG keys; privileges can be
 2461        granted or denied based on the key name.
 2462      </para>
 2463
 2464      <para>
 2465        When a SIG(0) signed message is received, it will only be
 2466        verified if the key is known and trusted by the server; the server
 2467        will not attempt to locate and/or validate the key.
 2468      </para>
 2469
 2470      <para>
 2471        SIG(0) signing of multiple-message TCP streams is not
 2472        supported.
 2473      </para>
 2474
 2475      <para>
 2476        The only tool shipped with <acronym>BIND</acronym> 9 that
 2477        generates SIG(0) signed messages is <command>nsupdate</command>.
 2478      </para>
 2479
 2480    </sect1>
 2481    <sect1 id="DNSSEC">
 2482      <title>DNSSEC</title>
 2483
 2484      <para>
 2485        Cryptographic authentication of DNS information is possible
 2486        through the DNS Security (<emphasis>DNSSEC-bis</emphasis>) extensions,
 2487        defined in RFC 4033, RFC 4034, and RFC 4035.
 2488	This section describes the creation and use of DNSSEC signed zones.
 2489      </para>
 2490
 2491      <para>
 2492        In order to set up a DNSSEC secure zone, there are a series
 2493        of steps which must be followed.  <acronym>BIND</acronym>
 2494        9 ships
 2495        with several tools
 2496        that are used in this process, which are explained in more detail
 2497        below.  In all cases, the <option>-h</option> option prints a
 2498        full list of parameters.  Note that the DNSSEC tools require the
 2499        keyset files to be in the working directory or the
 2500        directory specified by the <option>-d</option> option, and
 2501        that the tools shipped with BIND 9.2.x and earlier are not compatible
 2502        with the current ones.
 2503      </para>
 2504
 2505      <para>
 2506        There must also be communication with the administrators of
 2507        the parent and/or child zone to transmit keys.  A zone's security
 2508        status must be indicated by the parent zone for a DNSSEC capable
 2509        resolver to trust its data.  This is done through the presence
 2510        or absence of a <literal>DS</literal> record at the
 2511        delegation
 2512        point.
 2513      </para>
 2514
 2515      <para>
 2516        For other servers to trust data in this zone, they must
 2517        either be statically configured with this zone's zone key or the
 2518        zone key of another zone above this one in the DNS tree.
 2519      </para>
 2520
 2521      <sect2>
 2522        <title>Generating Keys</title>
 2523
 2524        <para>
 2525          The <command>dnssec-keygen</command> program is used to
 2526          generate keys.
 2527        </para>
 2528
 2529        <para>
 2530          A secure zone must contain one or more zone keys.  The
 2531          zone keys will sign all other records in the zone, as well as
 2532          the zone keys of any secure delegated zones.  Zone keys must
 2533          have the same name as the zone, a name type of
 2534          <command>ZONE</command>, and must be usable for
 2535          authentication.
 2536          It is recommended that zone keys use a cryptographic algorithm
 2537          designated as "mandatory to implement" by the IETF; currently
 2538          the only one is RSASHA1.
 2539        </para>
 2540
 2541        <para>
 2542          The following command will generate a 768-bit RSASHA1 key for
 2543          the <filename>child.example</filename> zone:
 2544        </para>
 2545
 2546        <para>
 2547          <userinput>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</userinput>
 2548        </para>
 2549
 2550        <para>
 2551          Two output files will be produced:
 2552          <filename>Kchild.example.+005+12345.key</filename> and
 2553          <filename>Kchild.example.+005+12345.private</filename>
 2554          (where
 2555          12345 is an example of a key tag).  The key filenames contain
 2556          the key name (<filename>child.example.</filename>),
 2557          algorithm (3
 2558          is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in
 2559          this case).
 2560          The private key (in the <filename>.private</filename>
 2561          file) is
 2562          used to generate signatures, and the public key (in the
 2563          <filename>.key</filename> file) is used for signature
 2564          verification.
 2565        </para>
 2566
 2567        <para>
 2568          To generate another key with the same properties (but with
 2569          a different key tag), repeat the above command.
 2570        </para>
 2571
 2572        <para>
 2573          The <command>dnssec-keyfromlabel</command> program is used
 2574          to get a key pair from a crypto hardware and build the key
 2575          files. Its usage is similar to <command>dnssec-keygen</command>.
 2576        </para>
 2577
 2578        <para>
 2579          The public keys should be inserted into the zone file by
 2580          including the <filename>.key</filename> files using
 2581          <command>$INCLUDE</command> statements.
 2582        </para>
 2583
 2584      </sect2>
 2585      <sect2>
 2586        <title>Signing the Zone</title>
 2587
 2588	<para>
 2589	  The <command>dnssec-signzone</command> program is used
 2590	  to sign a zone.
 2591	</para>
 2592
 2593	<para>
 2594	  Any <filename>keyset</filename> files corresponding to
 2595	  secure subzones should be present.  The zone signer will
 2596	  generate <literal>NSEC</literal>, <literal>NSEC3</literal>
 2597	  and <literal>RRSIG</literal> records for the zone, as
 2598	  well as <literal>DS</literal> for the child zones if
 2599	  <literal>'-g'</literal> is specified.  If <literal>'-g'</literal>
 2600	  is not specified, then DS RRsets for the secure child
 2601	  zones need to be added manually.
 2602	</para>
 2603
 2604        <para>
 2605          The following command signs the zone, assuming it is in a
 2606          file called <filename>zone.child.example</filename>.  By
 2607                default, all zone keys which have an available private key are
 2608                used to generate signatures.
 2609        </para>
 2610
 2611        <para>
 2612          <userinput>dnssec-signzone -o child.example zone.child.example</userinput>
 2613        </para>
 2614
 2615        <para>
 2616          One output file is produced:
 2617          <filename>zone.child.example.signed</filename>.  This
 2618          file
 2619          should be referenced by <filename>named.conf</filename>
 2620          as the
 2621          input file for the zone.
 2622        </para>
 2623
 2624        <para><command>dnssec-signzone</command>
 2625	  will also produce a keyset and dsset files and optionally a
 2626          dlvset file.  These are used to provide the parent zone
 2627          administrators with the <literal>DNSKEYs</literal> (or their
 2628          corresponding <literal>DS</literal> records) that are the
 2629          secure entry point to the zone.
 2630        </para>
 2631
 2632      </sect2>
 2633
 2634      <sect2>
 2635        <title>Configuring Servers</title>
 2636
 2637	<para>
 2638	  To enable <command>named</command> to respond appropriately
 2639	  to DNS requests from DNSSEC aware clients,
 2640	  <command>dnssec-enable</command> must be set to yes.
 2641          (This is the default setting.)
 2642        </para>
 2643
 2644	<para>
 2645	  To enable <command>named</command> to validate answers from
 2646	  other servers, the <command>dnssec-enable</command> option
 2647          must be set to <userinput>yes</userinput>, and the
 2648          <command>dnssec-validation</command> options must be set to 
 2649          <userinput>yes</userinput> or <userinput>auto</userinput>.
 2650        </para>
 2651	  
 2652	<para>
 2653          If <command>dnssec-validation</command> is set to
 2654          <userinput>auto</userinput>, then a default
 2655          trust anchor for the DNS root zone will be used.
 2656          If it is set to <userinput>yes</userinput>, however,
 2657          then at least one trust anchor must be configured
 2658          with a <command>trusted-keys</command> or
 2659          <command>managed-keys</command> statement in
 2660          <filename>named.conf</filename>, or DNSSEC validation
 2661          will not occur.  The default setting is
 2662          <userinput>yes</userinput>.
 2663        </para>
 2664	  
 2665	<para>
 2666	  <command>trusted-keys</command> are copies of DNSKEY RRs
 2667	  for zones that are used to form the first link in the
 2668	  cryptographic chain of trust.  All keys listed in
 2669	  <command>trusted-keys</command> (and corresponding zones)
 2670	  are deemed to exist and only the listed keys will be used
 2671	  to validated the DNSKEY RRset that they are from.
 2672	</para>
 2673
 2674	<para>
 2675	  <command>managed-keys</command> are trusted keys which are
 2676          automatically kept up to date via RFC 5011 trust anchor
 2677          maintenance.
 2678	</para>
 2679
 2680	<para>
 2681	  <command>trusted-keys</command> and
 2682          <command>managed-keys</command> are described in more detail
 2683	  later in this document.
 2684	</para>
 2685
 2686	<para>
 2687	  Unlike <acronym>BIND</acronym> 8, <acronym>BIND</acronym>
 2688	  9 does not verify signatures on load, so zone keys for
 2689	  authoritative zones do not need to be specified in the
 2690	  configuration file.
 2691	</para>
 2692
 2693	<para>
 2694	  After DNSSEC gets established, a typical DNSSEC configuration
 2695	  will look something like the following.  It has one or
 2696	  more public keys for the root.  This allows answers from
 2697	  outside the organization to be validated.  It will also
 2698	  have several keys for parts of the namespace the organization
 2699          controls.  These are here to ensure that <command>named</command>
 2700          is immune to compromises in the DNSSEC components of the security
 2701          of parent zones.
 2702	</para>
 2703
 2704<programlisting>
 2705managed-keys {
 2706	/* Root Key */
 2707        "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS
 2708                                 JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh
 2709                                 aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy
 2710                                 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg
 2711                                 hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp
 2712                                 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke
 2713                                 g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq
 2714                                 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ
 2715                                 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ
 2716                                 dgxbcDTClU0CRBdiieyLMNzXG3";
 2717};
 2718
 2719trusted-keys {
 2720        /* Key for our organization's forward zone */
 2721        example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
 2722                              5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z
 2723                              GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb
 2724                              4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL
 2725                              kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O
 2726                              g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S
 2727                              TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq
 2728                              FxmAVZP20igTixin/1LcrgX/KMEGd/biuv
 2729                              F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm
 2730                              /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o
 2731                              1OTQ09A0=";
 2732
 2733        /* Key for our reverse zone. */
 2734        2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
 2735                                       xOdNax071L18QqZnQQQAVVr+i
 2736                                       LhGTnNGp3HoWQLUIzKrJVZ3zg
 2737                                       gy3WwNT6kZo6c0tszYqbtvchm
 2738                                       gQC8CzKojM/W16i6MG/eafGU3
 2739                                       siaOdS0yOI6BgPsw+YZdzlYMa
 2740                                       IJGf4M4dyoKIhzdZyQ2bYQrjy
 2741                                       Q4LB0lC7aOnsMyYKHHYeRvPxj
 2742                                       IQXmdqgOJGq+vsevG06zW+1xg
 2743                                       YJh9rCIfnm1GX/KMgxLPG2vXT
 2744                                       D/RnLX+D3T3UL7HJYHJhAZD5L
 2745                                       59VvjSPsZJHeDCUyWYrvPZesZ
 2746                                       DIRvhDD52SKvbheeTJUm6Ehkz
 2747                                       ytNN2SN96QRk8j/iI8ib";
 2748};
 2749
 2750options {
 2751	...
 2752	dnssec-enable yes;
 2753	dnssec-validation yes;
 2754};
 2755</programlisting>
 2756
 2757	<note>
 2758	  None of the keys listed in this example are valid.  In particular,
 2759	  the root key is not valid.
 2760	</note>
 2761
 2762	<para>
 2763	  When DNSSEC validation is enabled and properly configured,
 2764	  the resolver will reject any answers from signed, secure zones
 2765	  which fail to validate, and will return SERVFAIL to the client.
 2766	</para>
 2767
 2768	<para>
 2769	  Responses may fail to validate for any of several reasons,
 2770	  including missing, expired, or invalid signatures, a key which
 2771	  does not match the DS RRset in the parent zone, or an insecure
 2772	  response from a zone which, according to its parent, should have
 2773	  been secure.  
 2774	</para>
 2775
 2776	<note>
 2777	  <para>
 2778	    When the validator receives a response from an unsigned zone
 2779	    that has a signed parent, it must confirm with the parent
 2780	    that the zone was intentionally left unsigned.  It does
 2781	    this by verifying, via signed and validated NSEC/NSEC3 records,
 2782	    that the parent zone contains no DS records for the child.
 2783	  </para>
 2784	  <para>
 2785	    If the validator <emphasis>can</emphasis> prove that the zone
 2786	    is insecure, then the response is accepted.  However, if it
 2787	    cannot, then it must assume an insecure response to be a
 2788	    forgery; it rejects the response and logs an error.
 2789	  </para>
 2790	  <para>
 2791            The logged error reads "insecurity proof failed" and
 2792            "got insecure response; parent indicates it should be secure".
 2793	    (Prior to BIND 9.7, the logged error was "not insecure".
 2794            This referred to the zone, not the response.)
 2795	  </para>
 2796	</note>
 2797      </sect2>
 2798
 2799    </sect1>
 2800
 2801    <xi:include href="dnssec.xml"/>
 2802
 2803    <xi:include href="managed-keys.xml"/>
 2804
 2805    <xi:include href="pkcs11.xml"/>
 2806
 2807    <sect1>
 2808      <title>IPv6 Support in <acronym>BIND</acronym> 9</title>
 2809
 2810      <para>
 2811        <acronym>BIND</acronym> 9 fully supports all currently
 2812        defined forms of IPv6 name to address and address to name
 2813        lookups.  It will also use IPv6 addresses to make queries when
 2814        running on an IPv6 capable system.
 2815      </para>
 2816
 2817      <para>
 2818        For forward lookups, <acronym>BIND</acronym> 9 supports
 2819        only AAAA records.  RFC 3363 deprecated the use of A6 records,
 2820        and client-side support for A6 records was accordingly removed
 2821        from <acronym>BIND</acronym> 9.
 2822        However, authoritative <acronym>BIND</acronym> 9 name servers still
 2823        load zone files containing A6 records correctly, answer queries
 2824        for A6 records, and accept zone transfer for a zone containing A6
 2825        records.
 2826      </para>
 2827
 2828      <para>
 2829        For IPv6 reverse lookups, <acronym>BIND</acronym> 9 supports
 2830        the traditional "nibble" format used in the
 2831        <emphasis>ip6.arpa</emphasis> domain, as well as the older, deprecated
 2832        <emphasis>ip6.int</emphasis> domain.
 2833        Older versions of <acronym>BIND</acronym> 9 
 2834        supported the "binary label" (also known as "bitstring") format,
 2835        but support of binary labels has been completely removed per
 2836        RFC 3363.
 2837        Many applications in <acronym>BIND</acronym> 9 do not understand
 2838        the binary label format at all any more, and will return an
 2839        error if given.
 2840	In particular, an authoritative <acronym>BIND</acronym> 9
 2841        name server will not load a zone file containing binary labels.
 2842      </para>
 2843
 2844      <para>
 2845        For an overview of the format and structure of IPv6 addresses,
 2846        see <xref linkend="ipv6addresses"/>.
 2847      </para>
 2848
 2849      <sect2>
 2850        <title>Address Lookups Using AAAA Records</title>
 2851
 2852        <para>
 2853          The IPv6 AAAA record is a parallel to the IPv4 A record,
 2854          and, unlike the deprecated A6 record, specifies the entire
 2855          IPv6 address in a single record.  For example,
 2856        </para>
 2857
 2858<programlisting>
 2859$ORIGIN example.com.
 2860host            3600    IN      AAAA    2001:db8::1
 2861</programlisting>
 2862
 2863        <para>
 2864          Use of IPv4-in-IPv6 mapped addresses is not recommended.
 2865	  If a host has an IPv4 address, use an A record, not
 2866          a AAAA, with <literal>::ffff:192.168.42.1</literal> as
 2867          the address.
 2868        </para>
 2869      </sect2>
 2870      <sect2>
 2871        <title>Address to Name Lookups Using Nibble Format</title>
 2872
 2873        <para>
 2874          When looking up an address in nibble format, the address
 2875          components are simply reversed, just as in IPv4, and
 2876          <literal>ip6.arpa.</literal> is appended to the
 2877          resulting name.
 2878          For example, the following would provide reverse name lookup for
 2879          a host with address
 2880          <literal>2001:db8::1</literal>.
 2881        </para>
 2882
 2883<programlisting>
 2884$ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
 28851.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0  14400   IN    PTR    (
 2886                                    host.example.com. )
 2887</programlisting>
 2888
 2889      </sect2>
 2890    </sect1>
 2891  </chapter>
 2892
 2893  <chapter id="Bv9ARM.ch05">
 2894    <title>The <acronym>BIND</acronym> 9 Lightweight Resolver</title>
 2895    <sect1>
 2896      <title>The Lightweight Resolver Library</title>
 2897      <para>
 2898        Traditionally applications have been linked with a stub resolver
 2899        library that sends recursive DNS queries to a local caching name
 2900        server.
 2901      </para>
 2902      <para>
 2903        IPv6 once introduced new complexity into the resolution process,
 2904        such as following A6 chains and DNAME records, and simultaneous
 2905        lookup of IPv4 and IPv6 addresses.  Though most of the complexity was
 2906        then removed, these are hard or impossible
 2907        to implement in a traditional stub resolver.
 2908      </para>
 2909      <para>
 2910        <acronym>BIND</acronym> 9 therefore can also provide resolution
 2911        services to local clients
 2912        using a combination of a lightweight resolver library and a resolver
 2913        daemon process running on the local host.  These communicate using
 2914        a simple UDP-based protocol, the "lightweight resolver protocol"
 2915        that is distinct from and simpler than the full DNS protocol.
 2916      </para>
 2917    </sect1>
 2918    <sect1 id="lwresd">
 2919      <title>Running a Resolver Daemon</title>
 2920
 2921      <para>
 2922        To use the lightweight resolver interface, the system must
 2923        run the resolver daemon <command>lwresd</command> or a
 2924        local
 2925        name server configured with a <command>lwres</command>
 2926        statement.
 2927      </para>
 2928
 2929      <para>
 2930        By default, applications using the lightweight resolver library will
 2931        make
 2932        UDP requests to the IPv4 loopback address (127.0.0.1) on port 921.
 2933        The
 2934        address can be overridden by <command>lwserver</command>
 2935        lines in
 2936        <filename>/etc/resolv.conf</filename>.
 2937      </para>
 2938
 2939      <para>
 2940        The daemon currently only looks in the DNS, but in the future
 2941        it may use other sources such as <filename>/etc/hosts</filename>,
 2942        NIS, etc.
 2943      </para>
 2944
 2945      <para>
 2946        The <command>lwresd</command> daemon is essentially a
 2947        caching-only name server that responds to requests using the
 2948        lightweight
 2949        resolver protocol rather than the DNS protocol.  Because it needs
 2950        to run on each host, it is designed to require no or minimal
 2951        configuration.
 2952        Unless configured otherwise, it uses the name servers listed on
 2953        <command>nameserver</command> lines in <filename>/etc/resolv.conf</filename>
 2954        as forwarders, but is also capable of doing the resolution
 2955        autonomously if
 2956        none are specified.
 2957      </para>
 2958      <para>
 2959        The <command>lwresd</command> daemon may also be
 2960        configured with a
 2961        <filename>named.conf</filename> style configuration file,
 2962        in
 2963        <filename>/etc/lwresd.conf</filename> by default.  A name
 2964        server may also
 2965        be configured to act as a lightweight resolver daemon using the
 2966        <command>lwres</command> statement in <filename>named.conf</filename>.
 2967      </para>
 2968
 2969    </sect1>
 2970  </chapter>
 2971
 2972  <chapter id="Bv9ARM.ch06">
 2973    <title><acronym>BIND</acronym> 9 Configuration Reference</title>
 2974
 2975    <para>
 2976      <acronym>BIND</acronym> 9 configuration is broadly similar
 2977      to <acronym>BIND</acronym> 8; however, there are a few new
 2978      areas
 2979      of configuration, such as views. <acronym>BIND</acronym>
 2980      8 configuration files should work with few alterations in <acronym>BIND</acronym>
 2981      9, although more complex configurations should be reviewed to check
 2982      if they can be more efficiently implemented using the new features
 2983      found in <acronym>BIND</acronym> 9.
 2984    </para>
 2985
 2986    <para>
 2987      <acronym>BIND</acronym> 4 configuration files can be
 2988      converted to the new format
 2989      using the shell script
 2990      <filename>contrib/named-bootconf/named-bootconf.sh</filename>.
 2991    </para>
 2992    <sect1 id="configuration_file_elements">
 2993      <title>Configuration File Elements</title>
 2994      <para>
 2995        Following is a list of elements used throughout the <acronym>BIND</acronym> configuration
 2996        file documentation:
 2997      </para>
 2998      <informaltable colsep="0" rowsep="0">
 2999        <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
 3000          <colspec colname="1" colnum="1" colsep="0" colwidth="1.855in"/>
 3001          <colspec colname="2" colnum="2" colsep="0" colwidth="3.770in"/>
 3002          <tbody>
 3003            <row rowsep="0">
 3004              <entry colname="1">
 3005                <para>
 3006                  <varname>acl_name</varname>
 3007                </para>
 3008              </entry>
 3009              <entry colname="2">
 3010                <para>
 3011                  The name of an <varname>address_match_list</varname> as
 3012                  defined by the <command>acl</command> statement.
 3013                </para>
 3014              </entry>
 3015            </row>
 3016            <row rowsep="0">
 3017              <entry colname="1">
 3018                <para>
 3019                  <varname>address_match_list</varname>
 3020                </para>
 3021              </entry>
 3022              <entry colname="2">
 3023                <para>
 3024                  A list of one or more
 3025                  <varname>ip_addr</varname>,
 3026                  <varname>ip_prefix</varname>, <varname>key_id</varname>,
 3027                  or <varname>acl_name</varname> elements, see
 3028                  <xref linkend="address_match_lists"/>.
 3029                </para>
 3030              </entry>
 3031            </row>
 3032            <row rowsep="0">
 3033              <entry colname="1">
 3034                <para>
 3035                  <varname>masters_list</varname>
 3036                </para>
 3037              </entry>
 3038              <entry colname="2">
 3039                <para>
 3040                  A named list of one or more <varname>ip_addr</varname>
 3041		  with optional <varname>key_id</varname> and/or
 3042		  <varname>ip_port</varname>.
 3043		  A <varname>masters_list</varname> may include other
 3044		  <varname>masters_lists</varname>.
 3045                </para>
 3046              </entry>
 3047            </row>
 3048            <row rowsep="0">
 3049              <entry colname="1">
 3050                <para>
 3051                  <varname>domain_name</varname>
 3052                </para>
 3053              </entry>
 3054              <entry colname="2">
 3055                <para>
 3056                  A quoted string which will be used as
 3057                  a DNS name, for example "<literal>my.test.domain</literal>".
 3058                </para>
 3059              </entry>
 3060            </row>
 3061            <row rowsep="0">
 3062              <entry colname="1">
 3063                <para>
 3064                  <varname>namelist</varname>
 3065                </para>
 3066              </entry>
 3067              <entry colname="2">
 3068                <para>
 3069                  A list of one or more <varname>domain_name</varname>
 3070                  elements.
 3071                </para>
 3072              </entry>
 3073            </row>
 3074            <row rowsep="0">
 3075              <entry colname="1">
 3076                <para>
 3077                  <varname>dotted_decimal</varname>
 3078                </para>
 3079              </entry>
 3080              <entry colname="2">
 3081                <para>
 3082                  One to four integers valued 0 through
 3083                  255 separated by dots (`.'), such as <command>123</command>,
 3084                  <command>45.67</command> or <command>89.123.45.67</command>.
 3085                </para>
 3086              </entry>
 3087            </row>
 3088            <row rowsep="0">
 3089              <entry colname="1">
 3090                <para>
 3091                  <varname>ip4_addr</varname>
 3092                </para>
 3093              </entry>
 3094              <entry colname="2">
 3095                <para>
 3096                  An IPv4 address with exactly four elements
 3097                  in <varname>dotted_decimal</varname> notation.
 3098                </para>
 3099              </entry>
 3100            </row>
 3101            <row rowsep="0">
 3102              <entry colname="1">
 3103                <para>
 3104                  <varname>ip6_addr</varname>
 3105                </para>
 3106              </entry>
 3107	      <entry colname="2">
 3108		<para>
 3109		  An IPv6 address, such as <command>2001:db8::1234</command>.
 3110		  IPv6 scoped addresses that have ambiguity on their
 3111		  scope zones must be disambiguated by an appropriate
 3112		  zone ID with the percent character (`%') as
 3113		  delimiter.  It is strongly recommended to use
 3114		  string zone names rather than numeric identifiers,
 3115		  in order to be robust against system configuration
 3116		  changes.  However, since there is no standard
 3117		  mapping for such names and identifier values,
 3118		  currently only interface names as link identifiers
 3119		  are supported, assuming one-to-one mapping between
 3120		  interfaces and links.  For example, a link-local
 3121		  address <command>fe80::1</command> on the link
 3122		  attached to the interface <command>ne0</command>
 3123		  can be specified as <command>fe80::1%ne0</command>.
 3124		  Note that on most systems link-local addresses
 3125		  always have the ambiguity, and need to be
 3126		  disambiguated.
 3127		</para>
 3128	      </entry>
 3129	    </row>
 3130            <row rowsep="0">
 3131              <entry colname="1">
 3132                <para>
 3133                  <varname>ip_addr</varname>
 3134                </para>
 3135              </entry>
 3136              <entry colname="2">
 3137                <para>
 3138                  An <varname>ip4_addr</varname> or <varname>ip6_addr</varname>.
 3139                </para>
 3140              </entry>
 3141            </row>
 3142            <row rowsep="0">
 3143              <entry colname="1">
 3144                <para>
 3145                  <varname>ip_port</varname>
 3146                </para>
 3147              </entry>
 3148              <entry colname="2">
 3149                <para>
 3150                  An IP port <varname>number</varname>.
 3151                  The <varname>number</varname> is limited to 0
 3152                  through 65535, with values
 3153                  below 1024 typically restricted to use by processes running
 3154                  as root.
 3155                  In some cases, an asterisk (`*') character can be used as a
 3156                  placeholder to
 3157                  select a random high-numbered port.
 3158                </para>
 3159              </entry>
 3160            </row>
 3161            <row rowsep="0">
 3162              <entry colname="1">
 3163                <para>
 3164                  <varname>ip_prefix</varname>
 3165                </para>
 3166              </entry>
 3167              <entry colname="2">
 3168                <para>
 3169                  An IP network specified as an <varname>ip_addr</varname>,
 3170                  followed by a slash (`/') and then the number of bits in the
 3171                  netmask.
 3172                  Trailing zeros in a <varname>ip_addr</varname>
 3173                  may omitted.
 3174                  For example, <command>127/8</command> is the
 3175                  network <command>127.0.0.0</command> with
 3176                  netmask <command>255.0.0.0</command> and <command>1.2.3.0/28</command> is
 3177                  network <command>1.2.3.0</command> with netmask <command>255.255.255.240</command>.
 3178                </para>
 3179                <para>
 3180		  When specifying a prefix involving a IPv6 scoped address
 3181		  the scope may be omitted.  In that case the prefix will
 3182		  match packets from any scope.
 3183                </para>
 3184              </entry>
 3185            </row>
 3186            <row rowsep="0">
 3187              <entry colname="1">
 3188                <para>
 3189                  <varname>key_id</varname>
 3190                </para>
 3191              </entry>
 3192              <entry colname="2">
 3193                <para>
 3194                  A <varname>domain_name</varname> representing
 3195                  the name of a shared key, to be used for transaction
 3196                  security.
 3197                </para>
 3198              </entry>
 3199            </row>
 3200            <row rowsep="0">
 3201              <entry colname="1">
 3202                <para>
 3203                  <varname>key_list</varname>
 3204                </para>
 3205              </entry>
 3206              <entry colname="2">
 3207                <para>
 3208                  A list of one or more
 3209                  <varname>key_id</varname>s,
 3210                  separated by semicolons and ending with a semicolon.
 3211                </para>
 3212              </entry>
 3213            </row>
 3214            <row rowsep="0">
 3215              <entry colname="1">
 3216                <para>
 3217                  <varname>number</varname>
 3218                </para>
 3219              </entry>
 3220              <entry colname="2">
 3221                <para>
 3222                  A non-negative 32-bit integer
 3223                  (i.e., a number between 0 and 4294967295, inclusive).
 3224                  Its acceptable value might further
 3225                  be limited by the context in which it is used.
 3226                </para>
 3227              </entry>
 3228            </row>
 3229            <row rowsep="0">
 3230              <entry colname="1">
 3231                <para>
 3232                  <varname>path_name</varname>
 3233                </para>
 3234              </entry>
 3235              <entry colname="2">
 3236                <para>
 3237                  A quoted string which will be used as
 3238                  a pathname, such as <filename>zones/master/my.test.domain</filename>.
 3239                </para>
 3240              </entry>
 3241            </row>
 3242            <row rowsep="0">
 3243              <entry colname="1">
 3244                <para>
 3245                  <varname>port_list</varname>
 3246                </para>
 3247              </entry>
 3248              <entry colname="2">
 3249                <para>
 3250		  A list of an <varname>ip_port</varname> or a port
 3251		  range.
 3252		  A port range is specified in the form of
 3253		  <userinput>range</userinput> followed by
 3254		  two <varname>ip_port</varname>s,
 3255		  <varname>port_low</varname> and
 3256		  <varname>port_high</varname>, which represents
 3257		  port numbers from <varname>port_low</varname> through
 3258		  <varname>port_high</varname>, inclusive.
 3259		  <varname>port_low</varname> must not be larger than
 3260		  <varname>port_high</varname>.
 3261		  For example,
 3262		  <userinput>range 1024 65535</userinput> represents
 3263		  ports from 1024 through 65535.
 3264		  In either case an asterisk (`*') character is not
 3265		  allowed as a valid <varname>ip_port</varname>.
 3266                </para>
 3267              </entry>
 3268            </row>
 3269            <row rowsep="0">
 3270              <entry colname="1">
 3271                <para>
 3272                  <varname>size_spec</varname>
 3273                </para>
 3274              </entry>
 3275              <entry colname="2">
 3276                <para>
 3277                  A number, the word <userinput>unlimited</userinput>,
 3278                  or the word <userinput>default</userinput>.
 3279                </para>
 3280		<para>
 3281                  An <varname>unlimited</varname> <varname>size_spec</varname> requests unlimited
 3282                  use, or the maximum available amount. A <varname>default size_spec</varname> uses
 3283                  the limit that was in force when the server was started.
 3284                </para>
 3285                <para>
 3286                  A <varname>number</varname> can optionally be
 3287		  followed by a scaling factor:
 3288		  <userinput>K</userinput> or <userinput>k</userinput>
 3289		  for kilobytes,
 3290		  <userinput>M</userinput> or <userinput>m</userinput>
 3291		  for megabytes, and
 3292		  <userinput>G</userinput> or <userinput>g</userinput> for gigabytes,
 3293                  which scale by 1024, 1024*1024, and 1024*1024*1024
 3294                  respectively.
 3295                </para>
 3296                <para>
 3297                  The value must be representable as a 64-bit unsigned integer
 3298                  (0 to 18446744073709551615, inclusive).
 3299                  Using <varname>unlimited</varname> is the best
 3300                  way
 3301                  to safely set a really large number.
 3302                </para>
 3303              </entry>
 3304            </row>
 3305            <row rowsep="0">
 3306              <entry colname="1">
 3307                <para>
 3308                  <varname>yes_or_no</varname>
 3309                </para>
 3310              </entry>
 3311              <entry colname="2">
 3312                <para>
 3313                  Either <userinput>yes</userinput> or <userinput>no</userinput>.
 3314                  The words <userinput>true</userinput> and <userinput>false</userinput> are
 3315                  also accepted, as are the numbers <userinput>1</userinput>
 3316                  and <userinput>0</userinput>.
 3317                </para>
 3318              </entry>
 3319            </row>
 3320            <row rowsep="0">
 3321              <entry colname="1">
 3322                <para>
 3323                  <varname>dialup_option</varname>
 3324                </para>
 3325              </entry>
 3326              <entry colname="2">
 3327                <para>
 3328                  One of <userinput>yes</userinput>,
 3329                  <userinput>no</userinput>, <userinput>notify</userinput>,
 3330                  <userinput>notify-passive</userinput>, <userinput>refresh</userinput> or
 3331                  <userinput>passive</userinput>.
 3332                  When used in a zone, <userinput>notify-passive</userinput>,
 3333                  <userinput>refresh</userinput>, and <userinput>passive</userinput>
 3334                  are restricted to slave and stub zones.
 3335                </para>
 3336              </entry>
 3337            </row>
 3338          </tbody>
 3339        </tgroup>
 3340      </informaltable>
 3341      <sect2 id="address_match_lists">
 3342        <title>Address Match Lists</title>
 3343        <sect3>
 3344          <title>Syntax</title>
 3345
 3346<programlisting><varname>address_match_list</varname> = address_match_list_element ;
 3347  <optional> address_match_list_element; ... </optional>
 3348<varname>address_match_list_element</varname> = <optional> ! </optional> (ip_address <optional>/length</optional> |
 3349   key key_id | acl_name | { address_match_list } )
 3350</programlisting>
 3351
 3352        </sect3>
 3353        <sect3>
 3354          <title>Definition and Usage</title>
 3355          <para>
 3356            Address match lists are primarily used to determine access
 3357            control for various server operations. They are also used in
 3358            the <command>listen-on</command> and <command>sortlist</command>
 3359            statements. The elements which constitute an address match
 3360            list can be any of the following:
 3361          </para>
 3362          <itemizedlist>
 3363            <listitem>
 3364              <simpara>an IP address (IPv4 or IPv6)</simpara>
 3365            </listitem>
 3366            <listitem>
 3367              <simpara>an IP prefix (in `/' notation)</simpara>
 3368            </listitem>
 3369            <listitem>
 3370              <simpara>
 3371                a key ID, as defined by the <command>key</command>
 3372                statement
 3373              </simpara>
 3374            </listitem>
 3375            <listitem>
 3376              <simpara>the name of an address match list defined with
 3377                the <command>acl</command> statement
 3378              </simpara>
 3379            </listitem>
 3380            <listitem>
 3381              <simpara>a nested address match list enclosed in braces</simpara>
 3382            </listitem>
 3383          </itemizedlist>
 3384
 3385          <para>
 3386            Elements can be negated with a leading exclamation mark (`!'),
 3387            and the match list names "any", "none", "localhost", and
 3388            "localnets" are predefined. More information on those names
 3389            can be found in the description of the acl statement.
 3390          </para>
 3391
 3392          <para>
 3393            The addition of the key clause made the name of this syntactic
 3394            element something of a misnomer, since security keys can be used
 3395            to validate access without regard to a host or network address.
 3396            Nonetheless, the term "address match list" is still used
 3397            throughout the documentation.
 3398          </para>
 3399
 3400          <para>
 3401            When a given IP address or prefix is compared to an address
 3402            match list, the comparison takes place in approximately O(1)
 3403            time.  However, key comparisons require that the list of keys
 3404            be traversed until a matching key is found, and therefore may
 3405            be somewhat slower.
 3406          </para>
 3407
 3408          <para>
 3409            The interpretation of a match depends on whether the list is being
 3410            used for access control, defining <command>listen-on</command> ports, or in a
 3411            <command>sortlist</command>, and whether the element was negated.
 3412          </para>
 3413
 3414	  <para>
 3415	    When used as an access control list, a non-negated match
 3416	    allows access and a negated match denies access. If
 3417	    there is no match, access is denied. The clauses
 3418	    <command>allow-notify</command>,
 3419	    <command>allow-recursion</command>,
 3420	    <command>allow-recursion-on</command>,
 3421	    <command>allow-query</command>,
 3422	    <command>allow-query-on</command>,
 3423	    <command>allow-query-cache</command>,
 3424	    <command>allow-query-cache-on</command>,
 3425	    <command>allow-transfer</command>,
 3426	    <command>allow-update</command>,
 3427	    <command>allow-update-forwarding</command>, and
 3428	    <command>blackhole</command> all use address match
 3429	    lists.  Similarly, the <command>listen-on</command> option will cause the
 3430	    server to refuse queries on any of the machine's
 3431	    addresses which do not match the list.
 3432	  </para>
 3433
 3434          <para>
 3435            Order of insertion is significant.  If more than one element
 3436            in an ACL is found to match a given IP address or prefix,
 3437            preference will be given to the one that came
 3438            <emphasis>first</emphasis> in the ACL definition.
 3439            Because of this first-match behavior, an element that
 3440            defines a subset of another element in the list should
 3441            come before the broader element, regardless of whether
 3442            either is negated. For example, in
 3443            <command>1.2.3/24; ! 1.2.3.13;</command>
 3444            the 1.2.3.13 element is completely useless because the
 3445            algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24
 3446            element.  Using <command>! 1.2.3.13; 1.2.3/24</command> fixes
 3447            that problem by having 1.2.3.13 blocked by the negation, but
 3448            all other 1.2.3.* hosts fall through.
 3449          </para>
 3450        </sect3>
 3451      </sect2>
 3452
 3453      <sect2>
 3454        <title>Comment Syntax</title>
 3455
 3456        <para>
 3457          The <acronym>BIND</acronym> 9 comment syntax allows for
 3458          comments to appear
 3459          anywhere that whitespace may appear in a <acronym>BIND</acronym> configuration
 3460          file. To appeal to programmers of all kinds, they can be written
 3461          in the C, C++, or shell/perl style.
 3462        </para>
 3463
 3464        <sect3>
 3465          <title>Syntax</title>
 3466
 3467          <para>
 3468            <programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting>
 3469            <programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting>
 3470            <programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells
 3471# and perl</programlisting>
 3472          </para>
 3473        </sect3>
 3474        <sect3>
 3475          <title>Definition and Usage</title>
 3476          <para>
 3477            Comments may appear anywhere that whitespace may appear in
 3478            a <acronym>BIND</acronym> configuration file.
 3479          </para>
 3480          <para>
 3481            C-style comments start with the two characters /* (slash,
 3482            star) and end with */ (star, slash). Because they are completely
 3483            delimited with these characters, they can be used to comment only
 3484            a portion of a line or to span multiple lines.
 3485          </para>
 3486          <para>
 3487            C-style comments cannot be nested. For example, the following
 3488            is not valid because the entire comment ends with the first */:
 3489          </para>
 3490          <para>
 3491
 3492<programlisting>/* This is the start of a comment.
 3493   This is still part of the comment.
 3494/* This is an incorrect attempt at nesting a comment. */
 3495   This is no longer in any comment. */
 3496</programlisting>
 3497
 3498          </para>
 3499
 3500          <para>
 3501            C++-style comments start with the two characters // (slash,
 3502            slash) and continue to the end of the physical line. They cannot
 3503            be continued across multiple physical lines; to have one logical
 3504            comment span multiple lines, each line must use the // pair.
 3505            For example:
 3506          </para>
 3507          <para>
 3508
 3509<programlisting>// This is the start of a comment.  The next line
 3510// is a new comment, even though it is logically
 3511// part of the previous comment.
 3512</programlisting>
 3513
 3514          </para>
 3515          <para>
 3516            Shell-style (or perl-style, if you prefer) comments start
 3517            with the character <literal>#</literal> (number sign)
 3518            and continue to the end of the
 3519            physical line, as in C++ comments.
 3520            For example:
 3521          </para>
 3522
 3523          <para>
 3524
 3525<programlisting># This is the start of a comment.  The next line
 3526# is a new comment, even though it is logically
 3527# part of the previous comment.
 3528</programlisting>
 3529
 3530          </para>
 3531
 3532          <warning>
 3533            <para>
 3534              You cannot use the semicolon (`;') character
 3535              to start a comment such as you would in a zone file. The
 3536              semicolon indicates the end of a configuration
 3537              statement.
 3538            </para>
 3539          </warning>
 3540        </sect3>
 3541      </sect2>
 3542    </sect1>
 3543
 3544    <sect1 id="Configuration_File_Grammar">
 3545      <title>Configuration File Grammar</title>
 3546
 3547      <para>
 3548        A <acronym>BIND</acronym> 9 configuration consists of
 3549        statements and comments.
 3550        Statements end with a semicolon. Statements and comments are the
 3551        only elements that can appear without enclosing braces. Many
 3552        statements contain a block of sub-statements, which are also
 3553        terminated with a semicolon.
 3554      </para>
 3555
 3556      <para>
 3557        The following statements are supported:
 3558      </para>
 3559
 3560      <informaltable colsep="0" rowsep="0">
 3561        <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
 3562          <colspec colname="1" colnum="1" colsep="0" colwidth="1.336in"/>
 3563          <colspec colname="2" colnum="2" colsep="0" colwidth="3.778in"/>
 3564          <tbody>
 3565            <row rowsep="0">
 3566              <entry colname="1">
 3567                <para><command>acl</command></para>
 3568              </entry>
 3569              <entry colname="2">
 3570                <para>
 3571                  defines a named IP address
 3572                  matching list, for access control and other uses.
 3573                </para>
 3574              </entry>
 3575            </row>
 3576            <row rowsep="0">
 3577              <entry colname="1">
 3578                <para><command>controls</command></para>
 3579              </entry>
 3580              <entry colname="2">
 3581                <para>
 3582                  declares control channels to be used
 3583                  by the <command>rndc</command> utility.
 3584                </para>
 3585              </entry>
 3586            </row>
 3587            <row rowsep="0">
 3588              <entry colname="1">
 3589                <para><command>include</command></para>
 3590              </entry>
 3591              <entry colname="2">
 3592                <para>
 3593                  includes a file.
 3594                </para>
 3595              </entry>
 3596            </row>
 3597            <row rowsep="0">
 3598              <entry colname="1">
 3599                <para><command>key</command></para>
 3600              </entry>
 3601              <entry colname="2">
 3602                <para>
 3603                  specifies key information for use in
 3604                  authentication and authorization using TSIG.
 3605                </para>
 3606              </entry>
 3607            </row>
 3608            <row rowsep="0">
 3609              <entry colname="1">
 3610                <para><command>logging</command></para>
 3611              </entry>
 3612              <entry colname="2">
 3613                <para>
 3614                  specifies what the server logs, and where
 3615                  the log messages are sent.
 3616                </para>
 3617              </entry>
 3618            </row>
 3619            <row rowsep="0">
 3620              <entry colname="1">
 3621                <para><command>lwres</command></para>
 3622              </entry>
 3623              <entry colname="2">
 3624                <para>
 3625                  configures <command>named</command> to
 3626                  also act as a light-weight resolver daemon (<command>lwresd</command>).
 3627                </para>
 3628              </entry>
 3629            </row>
 3630            <row rowsep="0">
 3631              <entry colname="1">
 3632                <para><command>masters</command></para>
 3633              </entry>
 3634              <entry colname="2">
 3635                <para>
 3636                  defines a named masters list for
 3637                  inclusion in stub and slave zone masters clauses.
 3638                </para>
 3639              </entry>
 3640            </row>
 3641            <row rowsep="0">
 3642              <entry colname="1">
 3643                <para><command>options</command></para>
 3644              </entry>
 3645              <entry colname="2">
 3646                <para>
 3647                  controls global server configuration
 3648                  options and sets defaults for other statements.
 3649                </para>
 3650              </entry>
 3651            </row>
 3652            <row rowsep="0">
 3653              <entry colname="1">
 3654                <para><command>server</command></para>
 3655              </entry>
 3656              <entry colname="2">
 3657                <para>
 3658                  sets certain configuration options on
 3659                  a per-server basis.
 3660                </para>
 3661              </entry>
 3662            </row>
 3663            <row rowsep="0">
 3664              <entry colname="1">
 3665                <para><command>statistics-channels</command></para>
 3666              </entry>
 3667              <entry colname="2">
 3668                <para>
 3669		  declares communication channels to get access to
 3670		  <command>named</command> statistics.
 3671                </para>
 3672              </entry>
 3673            </row>
 3674            <row rowsep="0">
 3675              <entry colname="1">
 3676                <para><command>trusted-keys</command></para>
 3677              </entry>
 3678              <entry colname="2">
 3679                <para>
 3680                  defines trusted DNSSEC keys.
 3681                </para>
 3682              </entry>
 3683            </row>
 3684            <row rowsep="0">
 3685              <entry colname="1">
 3686                <para><command>managed-keys</command></para>
 3687              </entry>
 3688              <entry colname="2">
 3689                <para>
 3690                  lists DNSSEC keys to be kept up to date
 3691                  using RFC 5011 trust anchor maintenance.
 3692                </para>
 3693              </entry>
 3694            </row>
 3695            <row rowsep="0">
 3696              <entry colname="1">
 3697                <para><command>view</command></para>
 3698              </entry>
 3699              <entry colname="2">
 3700                <para>
 3701                  defines a view.
 3702                </para>
 3703              </entry>
 3704            </row>
 3705            <row rowsep="0">
 3706              <entry colname="1">
 3707                <para><command>zone</command></para>
 3708              </entry>
 3709              <entry colname="2">
 3710                <para>
 3711                  defines a zone.
 3712                </para>
 3713              </entry>
 3714            </row>
 3715          </tbody>
 3716        </tgroup>
 3717      </informaltable>
 3718
 3719      <para>
 3720        The <command>logging</command> and
 3721        <command>options</command> statements may only occur once
 3722        per
 3723        configuration.
 3724      </para>
 3725
 3726      <sect2>
 3727        <title><command>acl</command> Statement Grammar</title>
 3728
 3729<programlisting><command>acl</command> acl-name {
 3730    address_match_list
 3731};
 3732</programlisting>
 3733
 3734      </sect2>
 3735      <sect2 id="acl">
 3736        <title><command>acl</command> Statement Definition and
 3737          Usage</title>
 3738
 3739        <para>
 3740          The <command>acl</command> statement assigns a symbolic
 3741          name to an address match list. It gets its name from a primary
 3742          use of address match lists: Access Control Lists (ACLs).
 3743        </para>
 3744
 3745        <para>
 3746          Note that an address match list's name must be defined
 3747          with <command>acl</command> before it can be used
 3748          elsewhere; no forward references are allowed.
 3749        </para>
 3750
 3751        <para>
 3752          The following ACLs are built-in:
 3753        </para>
 3754
 3755        <informaltable colsep="0" rowsep="0">
 3756          <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table">
 3757            <colspec colname="1" colnum="1" colsep="0" colwidth="1.130in"/>
 3758            <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/>
 3759            <tbody>
 3760              <row rowsep="0">
 3761                <entry colname="1">
 3762                  <para><command>any</command></para>
 3763                </entry>
 3764                <entry colname="2">
 3765                  <para>
 3766                    Matches all hosts.
 3767                  </para>
 3768                </entry>
 3769              </row>
 3770              <row rowsep="0">
 3771                <entry colname="1">
 3772                  <para><command>none</command></para>
 3773                </entry>
 3774                <entry colname="2">
 3775                  <para>
 3776                    Matches no hosts.
 3777                  </para>
 3778                </entry>
 3779              </row>
 3780              <row rowsep="0">
 3781                <entry colname="1">
 3782                  <para><command>localhost</command></para>
 3783                </entry>
 3784                <entry colname="2">
 3785                  <para>
 3786                    Matches the IPv4 and IPv6 addresses of all network
 3787                    interfaces on the system.
 3788                  </para>
 3789                </entry>
 3790              </row>
 3791              <row rowsep="0">
 3792                <entry colname="1">
 3793                  <para><command>localnets</command></para>
 3794                </entry>
 3795                <entry colname="2">
 3796                  <para>
 3797                    Matches any host on an IPv4 or IPv6 network
 3798                    for which the system has an interface.
 3799                    Some systems do not provide a way to determine the prefix
 3800                    lengths of
 3801                    local IPv6 addresses.
 3802                    In such a case, <command>localnets</command>
 3803                    only matches the local
 3804                    IPv6 addresses, just like <command>localhost</command>.
 3805                  </para>
 3806                </entry>
 3807              </row>
 3808            </tbody>
 3809          </tgroup>
 3810        </informaltable>
 3811
 3812      </sect2>
 3813      <sect2>
 3814        <title><command>controls</command> Statement Grammar</title>
 3815
 3816<programlisting><command>controls</command> {
 3817   [ inet ( ip_addr | * ) [ port ip_port ]
 3818                allow { <replaceable> address_match_list </replaceable> }
 3819                keys { <replaceable>key_list</replaceable> }; ]
 3820   [ inet ...; ]
 3821   [ unix <replaceable>path</replaceable> perm <replaceable>number</replaceable> owner <replaceable>number</replaceable> group <replaceable>number</replaceable>
 3822     keys { <replaceable>key_list</replaceable> }; ]
 3823   [ unix ...; ]
 3824};
 3825</programlisting>
 3826
 3827      </sect2>
 3828
 3829      <sect2 id="controls_statement_definition_and_usage">
 3830        <title><command>controls</command> Statement Definition and
 3831          Usage</title>
 3832
 3833        <para>
 3834          The <command>controls</command> statement declares control
 3835          channels to be used by system administrators to control the
 3836          operation of the name server. These control channels are
 3837          used by the <command>rndc</command> utility to send
 3838          commands to and retrieve non-DNS results from a name server.
 3839        </para>
 3840
 3841        <para>
 3842          An <command>inet</command> control channel is a TCP socket
 3843	  listening at the specified <command>ip_port</command> on the
 3844	  specified <command>ip_addr</command>, which can be an IPv4 or IPv6
 3845	  address.  An <command>ip_addr</command> of <literal>*</literal> (asterisk) is
 3846	  interpreted as the IPv4 wildcard address; connections will be
 3847	  accepted on any of the system's IPv4 addresses.
 3848	  To listen on the IPv6 wildcard address,
 3849          use an <command>ip_addr</command> of <literal>::</literal>.
 3850          If you will only use <command>rndc</command> on the local host,
 3851          using the loopback address (<literal>127.0.0.1</literal>
 3852          or <literal>::1</literal>) is recommended for maximum security.
 3853        </para>
 3854
 3855        <para>
 3856          If no port is specified, port 953 is used. The asterisk
 3857	  "<literal>*</literal>" cannot be used for <command>ip_port</command>.
 3858        </para>
 3859
 3860        <para>
 3861          The ability to issue commands over the control channel is
 3862          restricted by the <command>allow</command> and
 3863          <command>keys</command> clauses.
 3864	  Connections to the control channel are permitted based on the
 3865          <command>address_match_list</command>.  This is for simple
 3866          IP address based filtering only; any <command>key_id</command>
 3867          elements of the <command>address_match_list</command>
 3868          are ignored.
 3869        </para>
 3870
 3871	<para>
 3872	  A <command>unix</command> control channel is a UNIX domain
 3873	  socket listening at the specified path in the file system.
 3874	  Access to the socket is specified by the <command>perm</command>,
 3875	  <command>owner</command> and <command>group</command> clauses.
 3876	  Note on some platforms (SunOS and Solaris) the permissions
 3877	  (<command>perm</command>) are applied to the parent directory
 3878	  as the permissions on the socket itself are ignored.
 3879	</para>
 3880
 3881        <para>
 3882          The primary authorization mechanism of the command
 3883          channel is the <command>key_list</command>, which
 3884          contains a list of <command>key_id</command>s.
 3885          Each <command>key_id</command> in the <command>key_list</command>
 3886	  is authorized to execute commands over the control channel.
 3887          See <xref linkend="rndc"/> in <xref linkend="admin_tools"/>)
 3888	  for information about configuring keys in <command>rndc</command>.
 3889        </para>
 3890
 3891        <para>
 3892          If no <command>controls</command> statement is present,
 3893          <command>named</command> will set up a default
 3894          control channel listening on the loopback address 127.0.0.1
 3895          and its IPv6 counterpart ::1.
 3896          In this case, and also when the <command>controls</command> statement
 3897          is present but does not have a <command>keys</command> clause,
 3898          <command>named</command> will attempt to load the command channel key
 3899          from the file <filename>rndc.key</filename> in
 3900          <filename>/etc</filename> (or whatever <varname>sysconfdir</varname>
 3901          was specified as when <acronym>BIND</acronym> was built).
 3902          To create a <filename>rndc.key</filename> file, run
 3903          <userinput>rndc-confgen -a</userinput>.
 3904        </para>
 3905
 3906        <para>
 3907          The <filename>rndc.key</filename> feature was created to
 3908          ease the transition of systems from <acronym>BIND</acronym> 8,
 3909          which did not have digital signatures on its command channel
 3910          messages and thus did not have a <command>keys</command> clause.
 3911
 3912          It makes it possible to use an existing <acronym>BIND</acronym> 8
 3913          configuration file in <acronym>BIND</acronym> 9 unchanged,
 3914          and still have <command>rndc</command> work the same way
 3915          <command>ndc</command> worked in BIND 8, simply by executing the
 3916          command <userinput>rndc-confgen -a</userinput> after BIND 9 is
 3917          installed.
 3918        </para>
 3919
 3920        <para>
 3921          Since the <filename>rndc.key</filename> feature
 3922          is only intended to allow the backward-compatible usage of
 3923          <acronym>BIND</acronym> 8 configuration files, this
 3924          feature does not
 3925          have a high degree of configurability.  You cannot easily change
 3926          the key name or the size of the secret, so you should make a
 3927          <filename>rndc.conf</filename> with your own key if you
 3928          wish to change
 3929          those things.  The <filename>rndc.key</filename> file
 3930          also has its
 3931          permissions set such that only the owner of the file (the user that
 3932          <command>named</command> is running as) can access it.
 3933          If you
 3934          desire greater flexibility in allowing other users to access
 3935          <command>rndc</command> commands, then you need to create
 3936          a
 3937          <filename>rndc.conf</filename> file and make it group
 3938          readable by a group
 3939          that contains the users who should have access.
 3940        </para>
 3941
 3942        <para>
 3943          To disable the command channel, use an empty
 3944	  <command>controls</command> statement:
 3945	  <command>controls { };</command>.
 3946        </para>
 3947
 3948      </sect2>
 3949      <sect2>
 3950        <title><command>include</command> Statement Grammar</title>
 3951        <programlisting><command>include</command> <replaceable>filename</replaceable>;</programlisting>
 3952      </sect2>
 3953      <sect2>
 3954        <title><command>include</command> Statement Definition and
 3955          Usage</title>
 3956
 3957        <para>
 3958          The <command>include</command> statement inserts the
 3959          specified file at the point where the <command>include</command>
 3960          statement is encountered. The <command>include</command>
 3961                statement facilitates the administration of configuration
 3962          files
 3963          by permitting the reading or writing of some things but not
 3964          others. For example, the statement could include private keys
 3965          that are readable only by the name server.
 3966        </para>
 3967
 3968      </sect2>
 3969      <sect2>
 3970        <title><command>key</command> Statement Grammar</title>
 3971
 3972<programlisting><command>key</command> <replaceable>key_id</replaceable> {
 3973    algorithm <replaceable>string</replaceable>;
 3974    secret <replaceable>string</replaceable>;
 3975};
 3976</programlisting>
 3977
 3978      </sect2>
 3979
 3980      <sect2>
 3981        <title><command>key</command> Statement Definition and Usage</title>
 3982
 3983        <para>
 3984          The <command>key</command> statement defines a shared
 3985          secret key for use with TSIG (see <xref linkend="tsig"/>)
 3986          or the command channel
 3987          (see <xref linkend="controls_statement_definition_and_usage"/>).
 3988        </para>
 3989
 3990        <para>
 3991          The <command>key</command> statement can occur at the
 3992          top level
 3993          of the configuration file or inside a <command>view</command>
 3994          statement.  Keys defined in top-level <command>key</command>
 3995          statements can be used in all views.  Keys intended for use in
 3996          a <command>controls</command> statement
 3997          (see <xref linkend="controls_statement_definition_and_usage"/>)
 3998          must be defined at the top level.
 3999        </para>
 4000
 4001        <para>
 4002          The <replaceable>key_id</replaceable>, also known as the
 4003          key name, is a domain name uniquely identifying the key. It can
 4004          be used in a <command>server</command>
 4005          statement to cause requests sent to that
 4006          server to be signed with this key, or in address match lists to
 4007          verify that incoming requests have been signed with a key
 4008          matching this name, algorithm, and secret.
 4009        </para>
 4010
 4011	<para>
 4012	  The <replaceable>algorithm_id</replaceable> is a string
 4013	  that specifies a security/authentication algorithm.  Named
 4014	  supports <literal>hmac-md5</literal>,
 4015	  <literal>hmac-sha1</literal>, <literal>hmac-sha224</literal>,
 4016	  <literal>hmac-sha256</literal>, <literal>hmac-sha384</literal>
 4017	  and <literal>hmac-sha512</literal> TSIG authentication.
 4018	  Truncated hashes are supported by appending the minimum
 4019	  number of required bits preceded by a dash, e.g.
 4020	  <literal>hmac-sha1-80</literal>.  The
 4021	  <replaceable>secret_string</replaceable> is the secret
 4022	  to be used by the algorithm, and is treated as a base-64
 4023	  encoded string.
 4024	</para>
 4025
 4026      </sect2>
 4027      <sect2>
 4028        <title><command>logging</command> Statement Grammar</title>
 4029
 4030<programlisting><command>logging</command> {
 4031   [ <command>channel</command> <replaceable>channel_name</replaceable> {
 4032     ( <command>file</command> <replaceable>path_name</replaceable>
 4033         [ <command>versions</command> ( <replaceable>number</replaceable> | <command>unlimited</command> ) ]
 4034         [ <command>size</command> <replaceable>size spec</replaceable> ]
 4035       | <command>syslog</command> <replaceable>syslog_facility</replaceable>
 4036       | <command>stderr</command>
 4037       | <command>null</command> );
 4038     [ <command>severity</command> (<option>critical</option> | <option>error</option> | <option>warning</option> | <option>notice</option> |
 4039                 <option>info</option> | <option>debug</option> [ <replaceable>level</replaceable> ] | <option>dynamic</option> ); ]
 4040     [ <command>print-category</command> <option>yes</option> or <option>no</option>; ]
 4041     [ <command>print-severity</command> <option>yes</option> or <option>no</option>; ]
 4042     [ <command>print-time</command> <option>yes</option> or <option>no</option>; ]
 4043   }; ]
 4044   [ <command>category</command> <replaceable>category_name</replaceable> {
 4045     <replaceable>channel_name</replaceable> ; [ <replaceable>channel_name</replaceable> ; ... ]
 4046   }; ]
 4047   ...
 4048};
 4049</programlisting>
 4050
 4051      </sect2>
 4052
 4053      <sect2>
 4054        <title><command>logging</command> Statement Definition and
 4055          Usage</title>
 4056
 4057        <para>
 4058          The <command>logging</command> statement configures a
 4059          wide
 4060          variety of logging options for the name server. Its <command>channel</command> phrase
 4061          associates output methods, format options and severity levels with
 4062          a name that can then be used with the <command>category</command> phrase
 4063          to select how various classes of messages are logged.
 4064        </para>
 4065        <para>
 4066          Only one <command>logging</command> statement is used to
 4067          define
 4068          as many channels and categories as are wanted. If there is no <command>logging</command> statement,
 4069          the logging configuration will be:
 4070        </para>
 4071
 4072<programlisting>logging {
 4073     category default { default_syslog; default_debug; };
 4074     category unmatched { null; };
 4075};
 4076</programlisting>
 4077
 4078        <para>
 4079          In <acronym>BIND</acronym> 9, the logging configuration
 4080          is only established when
 4081          the entire configuration file has been parsed.  In <acronym>BIND</acronym> 8, it was
 4082          established as soon as the <command>logging</command>
 4083          statement
 4084          was parsed. When the server is starting up, all logging messages
 4085          regarding syntax errors in the configuration file go to the default
 4086          channels, or to standard error if the "<option>-g</option>" option
 4087          was specified.
 4088        </para>
 4089
 4090        <sect3>
 4091          <title>The <command>channel</command> Phrase</title>
 4092
 4093          <para>
 4094            All log output goes to one or more <emphasis>channels</emphasis>;
 4095            you can make as many of them as you want.
 4096          </para>
 4097
 4098          <para>
 4099            Every channel definition must include a destination clause that
 4100            says whether messages selected for the channel go to a file, to a
 4101            particular syslog facility, to the standard error stream, or are
 4102            discarded. It can optionally also limit the message severity level
 4103            that will be accepted by the channel (the default is
 4104            <command>info</command>), and whether to include a
 4105            <command>named</command>-generated time stamp, the
 4106            category name
 4107            and/or severity level (the default is not to include any).
 4108          </para>
 4109
 4110          <para>
 4111            The <command>null</command> destination clause
 4112            causes all messages sent to the channel to be discarded;
 4113            in that case, other options for the channel are meaningless.
 4114          </para>
 4115
 4116          <para>
 4117            The <command>file</command> destination clause directs
 4118            the channel
 4119            to a disk file.  It can include limitations
 4120            both on how large the file is allowed to become, and how many
 4121            versions
 4122            of the file will be saved each time the file is opened.
 4123          </para>
 4124
 4125          <para>
 4126            If you use the <command>versions</command> log file
 4127            option, then
 4128            <command>named</command> will retain that many backup
 4129            versions of the file by
 4130            renaming them when opening.  For example, if you choose to keep
 4131            three old versions
 4132            of the file <filename>lamers.log</filename>, then just
 4133            before it is opened
 4134            <filename>lamers.log.1</filename> is renamed to
 4135            <filename>lamers.log.2</filename>, <filename>lamers.log.0</filename> is renamed
 4136            to <filename>lamers.log.1</filename>, and <filename>lamers.log</filename> is
 4137            renamed to <filename>lamers.log.0</filename>.
 4138            You can say <command>versions unlimited</command> to
 4139            not limit
 4140            the number of versions.
 4141            If a <command>size</command> option is associated with
 4142            the log file,
 4143            then renaming is only done when the file being opened exceeds the
 4144            indicated size.  No backup versions are kept by default; any
 4145            existing
 4146            log file is simply appended.
 4147          </para>
 4148
 4149          <para>
 4150            The <command>size</command> option for files is used
 4151            to limit log
 4152            growth. If the file ever exceeds the size, then <command>named</command> will
 4153            stop writing to the file unless it has a <command>versions</command> option
 4154            associated with it.  If backup versions are kept, the files are
 4155            rolled as
 4156            described above and a new one begun.  If there is no
 4157            <command>versions</command> option, no more data will
 4158            be written to the log
 4159            until some out-of-band mechanism removes or truncates the log to
 4160            less than the
 4161            maximum size.  The default behavior is not to limit the size of
 4162            the
 4163            file.
 4164          </para>
 4165
 4166          <para>
 4167            Example usage of the <command>size</command> and
 4168            <command>versions</command> options:
 4169          </para>
 4170
 4171<programlisting>channel an_example_channel {
 4172    file "example.log" versions 3 size 20m;
 4173    print-time yes;
 4174    print-category yes;
 4175};
 4176</programlisting>
 4177
 4178          <para>
 4179            The <command>syslog</command> destination clause
 4180            directs the
 4181            channel to the system log.  Its argument is a
 4182            syslog facility as described in the <command>syslog</command> man
 4183            page. Known facilities are <command>kern</command>, <command>user</command>,
 4184            <command>mail</command>, <command>daemon</command>, <command>auth</command>,
 4185            <command>syslog</command>, <command>lpr</command>, <command>news</command>,
 4186            <command>uucp</command>, <command>cron</command>, <command>authpriv</command>,
 4187            <command>ftp</command>, <command>local0</command>, <command>local1</command>,
 4188            <command>local2</command>, <command>local3</command>, <command>local4</command>,
 4189            <command>local5</command>, <command>local6</command> and
 4190            <command>local7</command>, however not all facilities
 4191            are supported on
 4192            all operating systems.
 4193            How <command>syslog</command> will handle messages
 4194            sent to
 4195            this facility is described in the <command>syslog.conf</command> man
 4196            page. If you have a system which uses a very old version of <command>syslog</command> that
 4197            only uses two arguments to the <command>openlog()</command> function,
 4198            then this clause is silently ignored.
 4199          </para>
 4200          <para>
 4201            The <command>severity</command> clause works like <command>syslog</command>'s
 4202            "priorities", except that they can also be used if you are writing
 4203            straight to a file rather than using <command>syslog</command>.
 4204            Messages which are not at least of the severity level given will
 4205            not be selected for the channel; messages of higher severity
 4206            levels
 4207            will be accepted.
 4208          </para>
 4209          <para>
 4210            If you are using <command>syslog</command>, then the <command>syslog.conf</command> priorities
 4211            will also determine what eventually passes through. For example,
 4212            defining a channel facility and severity as <command>daemon</command> and <command>debug</command> but
 4213            only logging <command>daemon.warning</command> via <command>syslog.conf</command> will
 4214            cause messages of severity <command>info</command> and
 4215            <command>notice</command> to
 4216            be dropped. If the situation were reversed, with <command>named</command> writing
 4217            messages of only <command>warning</command> or higher,
 4218            then <command>syslogd</command> would
 4219            print all messages it received from the channel.
 4220          </para>
 4221
 4222          <para>
 4223            The <command>stderr</command> destination clause
 4224            directs the
 4225            channel to the server's standard error stream.  This is intended
 4226            for
 4227            use when the server is running as a foreground process, for
 4228            example
 4229            when debugging a configuration.
 4230          </para>
 4231
 4232          <para>
 4233            The server can supply extensive debugging information when
 4234            it is in debugging mode. If the server's global debug level is
 4235            greater
 4236            than zero, then debugging mode will be active. The global debug
 4237            level is set either by starting the <command>named</command> server
 4238            with the <option>-d</option> flag followed by a positive integer,
 4239            or by running <command>rndc trace</command>.
 4240            The global debug level
 4241            can be set to zero, and debugging mode turned off, by running <command>rndc
 4242notrace</command>. All debugging messages in the server have a debug
 4243            level, and higher debug levels give more detailed output. Channels
 4244            that specify a specific debug severity, for example:
 4245          </para>
 4246
 4247<programlisting>channel specific_debug_level {
 4248    file "foo";
 4249    severity debug 3;
 4250};
 4251</programlisting>
 4252
 4253          <para>
 4254            will get debugging output of level 3 or less any time the
 4255            server is in debugging mode, regardless of the global debugging
 4256            level. Channels with <command>dynamic</command>
 4257            severity use the
 4258            server's global debug level to determine what messages to print.
 4259          </para>
 4260          <para>
 4261            If <command>print-time</command> has been turned on,
 4262            then
 4263            the date and time will be logged. <command>print-time</command> may
 4264            be specified for a <command>syslog</command> channel,
 4265            but is usually
 4266            pointless since <command>syslog</command> also logs
 4267            the date and
 4268            time. If <command>print-category</command> is
 4269            requested, then the
 4270            category of the message will be logged as well. Finally, if <command>print-severity</command> is
 4271            on, then the severity level of the message will be logged. The <command>print-</command> options may
 4272            be used in any combination, and will always be printed in the
 4273            following
 4274            order: time, category, severity. Here is an example where all
 4275            three <command>print-</command> options
 4276            are on:
 4277          </para>
 4278
 4279          <para>
 4280            <computeroutput>28-Feb-2000 15:05:32.863 general: notice: running</computeroutput>
 4281          </para>
 4282
 4283          <para>
 4284            There are four predefined channels that are used for
 4285            <command>named</command>'s default logging as follows.
 4286            How they are
 4287            used is described in <xref linkend="the_category_phrase"/>.
 4288          </para>
 4289
 4290<programlisting>channel default_syslog {
 4291    // send to syslog's daemon facility
 4292    syslog daemon;
 4293    // only send priority info and higher
 4294    severity info;
 4295
 4296channel default_debug {
 4297    // write to named.run in the working directory
 4298    // Note: stderr is used instead of "named.run" if
 4299    // the server is started with the '-f' option.
 4300    file "named.run";
 4301    // log at the server's current debug level
 4302    severity dynamic;
 4303};
 4304
 4305channel default_stderr {
 4306    // writes to stderr
 4307    stderr;
 4308    // only send priority info and higher
 4309    severity info;
 4310};
 4311
 4312channel null {
 4313   // toss anything sent to this channel
 4314   null;
 4315};
 4316</programlisting>
 4317
 4318          <para>
 4319            The <command>default_debug</command> channel has the
 4320            special
 4321            property that it only produces output when the server's debug
 4322            level is
 4323            nonzero.  It normally writes to a file called <filename>named.run</filename>
 4324            in the server's working directory.
 4325          </para>
 4326
 4327          <para>
 4328            For security reasons, when the "<option>-u</option>"
 4329            command line option is used, the <filename>named.run</filename> file
 4330            is created only after <command>named</command> has
 4331            changed to the
 4332            new UID, and any debug output generated while <command>named</command> is
 4333            starting up and still running as root is discarded.  If you need
 4334            to capture this output, you must run the server with the "<option>-g</option>"
 4335            option and redirect standard error to a file.
 4336          </para>
 4337
 4338          <para>
 4339            Once a channel is defined, it cannot be redefined. Thus you
 4340            cannot alter the built-in channels directly, but you can modify
 4341            the default logging by pointing categories at channels you have
 4342            defined.
 4343          </para>
 4344        </sect3>
 4345
 4346        <sect3 id="the_category_phrase">
 4347          <title>The <command>category</command> Phrase</title>
 4348
 4349          <para>
 4350            There are many categories, so you can send the logs you want
 4351            to see wherever you want, without seeing logs you don't want. If
 4352            you don't specify a list of channels for a category, then log
 4353            messages
 4354            in that category will be sent to the <command>default</command> category
 4355            instead. If you don't specify a default category, the following
 4356            "default default" is used:
 4357          </para>
 4358
 4359<programlisting>category default { default_syslog; default_debug; };
 4360</programlisting>
 4361
 4362          <para>
 4363            As an example, let's say you want to log security events to
 4364            a file, but you also want keep the default logging behavior. You'd
 4365            specify the following:
 4366          </para>
 4367
 4368<programlisting>channel my_security_channel {
 4369    file "my_security_file";
 4370    severity info;
 4371};
 4372category security {
 4373    my_security_channel;
 4374    default_syslog;
 4375    default_debug;
 4376};</programlisting>
 4377
 4378          <para>
 4379            To discard all messages in a category, specify the <command>null</command> channel:
 4380          </para>
 4381
 4382<programlisting>category xfer-out { null; };
 4383category notify { null; };
 4384</programlisting>
 4385
 4386          <para>
 4387            Following are the available categories and brief descriptions
 4388            of the types of log information they contain. More
 4389            categories may be added in future <acronym>BIND</acronym> releases.
 4390          </para>
 4391          <informaltable colsep="0" rowsep="0">
 4392            <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 4393              <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/>
 4394              <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/>
 4395              <tbody>
 4396                <row rowsep="0">
 4397                  <entry colname="1">
 4398                    <para><command>default</command></para>
 4399                  </entry>
 4400                  <entry colname="2">
 4401                    <para>
 4402                      The default category defines the logging
 4403                      options for those categories where no specific
 4404                      configuration has been
 4405                      defined.
 4406                    </para>
 4407                  </entry>
 4408                </row>
 4409                <row rowsep="0">
 4410                  <entry colname="1">
 4411                    <para><command>general</command></para>
 4412                  </entry>
 4413                  <entry colname="2">
 4414                    <para>
 4415                      The catch-all. Many things still aren't
 4416                      classified into categories, and they all end up here.
 4417                    </para>
 4418                  </entry>
 4419                </row>
 4420                <row rowsep="0">
 4421                  <entry colname="1">
 4422                    <para><command>database</command></para>
 4423                  </entry>
 4424                  <entry colname="2">
 4425                    <para>
 4426                      Messages relating to the databases used
 4427                      internally by the name server to store zone and cache
 4428                      data.
 4429                    </para>
 4430                  </entry>
 4431                </row>
 4432                <row rowsep="0">
 4433                  <entry colname="1">
 4434                    <para><command>security</command></para>
 4435                  </entry>
 4436                  <entry colname="2">
 4437                    <para>
 4438                      Approval and denial of requests.
 4439                    </para>
 4440                  </entry>
 4441                </row>
 4442                <row rowsep="0">
 4443                  <entry colname="1">
 4444                    <para><command>config</command></para>
 4445                  </entry>
 4446                  <entry colname="2">
 4447                    <para>
 4448                      Configuration file parsing and processing.
 4449                    </para>
 4450                  </entry>
 4451                </row>
 4452                <row rowsep="0">
 4453                  <entry colname="1">
 4454                    <para><command>resolver</command></para>
 4455                  </entry>
 4456                  <entry colname="2">
 4457                    <para>
 4458                      DNS resolution, such as the recursive
 4459                      lookups performed on behalf of clients by a caching name
 4460                      server.
 4461                    </para>
 4462                  </entry>
 4463                </row>
 4464                <row rowsep="0">
 4465                  <entry colname="1">
 4466                    <para><command>xfer-in</command></para>
 4467                  </entry>
 4468                  <entry colname="2">
 4469                    <para>
 4470                      Zone transfers the server is receiving.
 4471                    </para>
 4472                  </entry>
 4473                </row>
 4474                <row rowsep="0">
 4475                  <entry colname="1">
 4476                    <para><command>xfer-out</command></para>
 4477                  </entry>
 4478                  <entry colname="2">
 4479                    <para>
 4480                      Zone transfers the server is sending.
 4481                    </para>
 4482                  </entry>
 4483                </row>
 4484                <row rowsep="0">
 4485                  <entry colname="1">
 4486                    <para><command>notify</command></para>
 4487                  </entry>
 4488                  <entry colname="2">
 4489                    <para>
 4490                      The NOTIFY protocol.
 4491                    </para>
 4492                  </entry>
 4493                </row>
 4494                <row rowsep="0">
 4495                  <entry colname="1">
 4496                    <para><command>client</command></para>
 4497                  </entry>
 4498                  <entry colname="2">
 4499                    <para>
 4500                      Processing of client requests.
 4501                    </para>
 4502                  </entry>
 4503                </row>
 4504                <row rowsep="0">
 4505                  <entry colname="1">
 4506                    <para><command>unmatched</command></para>
 4507                  </entry>
 4508                  <entry colname="2">
 4509                    <para>
 4510                      Messages that <command>named</command> was unable to determine the
 4511                      class of or for which there was no matching <command>view</command>.
 4512                      A one line summary is also logged to the <command>client</command> category.
 4513                      This category is best sent to a file or stderr, by
 4514                      default it is sent to
 4515                      the <command>null</command> channel.
 4516                    </para>
 4517                  </entry>
 4518                </row>
 4519                <row rowsep="0">
 4520                  <entry colname="1">
 4521                    <para><command>network</command></para>
 4522                  </entry>
 4523                  <entry colname="2">
 4524                    <para>
 4525                      Network operations.
 4526                    </para>
 4527                  </entry>
 4528                </row>
 4529                <row rowsep="0">
 4530                  <entry colname="1">
 4531                    <para><command>update</command></para>
 4532                  </entry>
 4533                  <entry colname="2">
 4534                    <para>
 4535                      Dynamic updates.
 4536                    </para>
 4537                  </entry>
 4538                </row>
 4539                <row rowsep="0">
 4540                  <entry colname="1">
 4541                    <para><command>update-security</command></para>
 4542                  </entry>
 4543                  <entry colname="2">
 4544                    <para>
 4545                      Approval and denial of update requests.
 4546                    </para>
 4547                  </entry>
 4548                </row>
 4549                <row rowsep="0">
 4550                  <entry colname="1">
 4551                    <para><command>queries</command></para>
 4552                  </entry>
 4553                  <entry colname="2">
 4554                    <para>
 4555                      Specify where queries should be logged to.
 4556                    </para>
 4557                    <para>
 4558                      At startup, specifying the category <command>queries</command> will also
 4559                      enable query logging unless <command>querylog</command> option has been
 4560                      specified.
 4561                    </para>
 4562
 4563		    <para>
 4564		      The query log entry reports the client's IP
 4565		      address and port number, and the query name,
 4566		      class and type.  Next it reports whether the
 4567		      Recursion Desired flag was set (+ if set, -
 4568		      if not set), if the query was signed (S),
 4569		      EDNS was in use (E), if TCP was used (T), if
 4570		      DO (DNSSEC Ok) was set (D), or if CD (Checking
 4571		      Disabled) was set (C).  After this the
 4572		      destination address the query was sent to is
 4573		      reported.
 4574		    </para>
 4575
 4576                    <para>
 4577                      <computeroutput>client 127.0.0.1#62536: query: www.example.com IN AAAA +SE</computeroutput>
 4578                    </para>
 4579                    <para>
 4580                      <computeroutput>client ::1#62537: query: www.example.net IN AAAA -SE</computeroutput>
 4581                    </para>
 4582                  </entry>
 4583                </row>
 4584                <row rowsep="0">
 4585                  <entry colname="1">
 4586                    <para><command>query-errors</command></para>
 4587                  </entry>
 4588                  <entry colname="2">
 4589                    <para>
 4590                      Information about queries that resulted in some
 4591                      failure.
 4592		    </para>
 4593		  </entry>
 4594		</row>
 4595                <row rowsep="0">
 4596                  <entry colname="1">
 4597                    <para><command>dispatch</command></para>
 4598                  </entry>
 4599                  <entry colname="2">
 4600                    <para>
 4601                      Dispatching of incoming packets to the
 4602                      server modules where they are to be processed.
 4603                    </para>
 4604                  </entry>
 4605                </row>
 4606                <row rowsep="0">
 4607                  <entry colname="1">
 4608                    <para><command>dnssec</command></para>
 4609                  </entry>
 4610                  <entry colname="2">
 4611                    <para>
 4612                      DNSSEC and TSIG protocol processing.
 4613                    </para>
 4614                  </entry>
 4615                </row>
 4616                <row rowsep="0">
 4617                  <entry colname="1">
 4618                    <para><command>lame-servers</command></para>
 4619                  </entry>
 4620                  <entry colname="2">
 4621                    <para>
 4622                      Lame servers.  These are misconfigurations
 4623                      in remote servers, discovered by BIND 9 when trying to
 4624                      query those servers during resolution.
 4625                    </para>
 4626                  </entry>
 4627                </row>
 4628                <row rowsep="0">
 4629                  <entry colname="1">
 4630                    <para><command>delegation-only</command></para>
 4631                  </entry>
 4632		  <entry colname="2">
 4633		    <para>
 4634		      Delegation only.  Logs queries that have been
 4635		      forced to NXDOMAIN as the result of a
 4636		      delegation-only zone or a
 4637		      <command>delegation-only</command> in a hint
 4638		      or stub zone declaration.
 4639		    </para>
 4640		  </entry>
 4641		</row>
 4642                <row rowsep="0">
 4643                  <entry colname="1">
 4644                    <para><command>edns-disabled</command></para>
 4645                  </entry>
 4646		  <entry colname="2">
 4647		    <para>
 4648		      Log queries that have been forced to use plain
 4649		      DNS due to timeouts.  This is often due to
 4650		      the remote servers not being RFC 1034 compliant
 4651		      (not always returning FORMERR or similar to
 4652		      EDNS queries and other extensions to the DNS
 4653		      when they are not understood).  In other words, this is
 4654		      targeted at servers that fail to respond to
 4655		      DNS queries that they don't understand.
 4656		    </para>
 4657		    <para>
 4658		      Note: the log message can also be due to
 4659		      packet loss.  Before reporting servers for
 4660		      non-RFC 1034 compliance they should be re-tested
 4661		      to determine the nature of the non-compliance.
 4662		      This testing should prevent or reduce the
 4663		      number of false-positive reports.
 4664		    </para>
 4665		    <para>
 4666		      Note: eventually <command>named</command> will have to stop
 4667		      treating such timeouts as due to RFC 1034 non
 4668		      compliance and start treating it as plain
 4669		      packet loss.  Falsely classifying packet
 4670		      loss as due to RFC 1034 non compliance impacts
 4671		      on DNSSEC validation which requires EDNS for
 4672		      the DNSSEC records to be returned.
 4673		    </para>
 4674		  </entry>
 4675		</row>
 4676                <row rowsep="0">
 4677                  <entry colname="1">
 4678                    <para><command>RPZ</command></para>
 4679                  </entry>
 4680		  <entry colname="2">
 4681		    <para>
 4682		      Information about errors in response policy zone files,
 4683		      rewritten responses, and at the highest
 4684		      <command>debug</command> levels, mere rewriting
 4685		      attempts.
 4686		    </para>
 4687		  </entry>
 4688		</row>
 4689	      </tbody>
 4690	    </tgroup>
 4691	  </informaltable>
 4692	</sect3>
 4693	<sect3>
 4694	  <title>The <command>query-errors</command> Category</title>
 4695	  <para>
 4696	    The <command>query-errors</command> category is
 4697	    specifically intended for debugging purposes: To identify
 4698	    why and how specific queries result in responses which
 4699	    indicate an error.
 4700	    Messages of this category are therefore only logged
 4701	    with <command>debug</command> levels.
 4702	  </para>
 4703
 4704	  <para>
 4705	    At the debug levels of 1 or higher, each response with the
 4706	    rcode of SERVFAIL is logged as follows:
 4707	  </para>
 4708	  <para>
 4709	    <computeroutput>client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</computeroutput>
 4710	  </para>
 4711	  <para>
 4712	    This means an error resulting in SERVFAIL was
 4713	    detected at line 3880 of source file
 4714	    <filename>query.c</filename>.
 4715	    Log messages of this level will particularly
 4716	    help identify the cause of SERVFAIL for an
 4717	    authoritative server.
 4718	  </para>
 4719	  <para>
 4720	    At the debug levels of 2 or higher, detailed context
 4721	    information of recursive resolutions that resulted in
 4722	    SERVFAIL is logged.
 4723	    The log message will look like as follows:
 4724	  </para>
 4725	  <para>
 4726<!-- NOTE: newlines and some spaces added so this would fit on page -->
 4727            <programlisting>
 4728fetch completed at resolver.c:2970 for www.example.com/A
 4729in 30.000183: timed out/success [domain:example.com,
 4730referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0,
 4731badresp:1,adberr:0,findfail:0,valfail:0]
 4732            </programlisting>
 4733	  </para>
 4734	  <para>
 4735	    The first part before the colon shows that a recursive
 4736	    resolution for AAAA records of www.example.com completed
 4737	    in 30.000183 seconds and the final result that led to the
 4738	    SERVFAIL was determined at line 2970 of source file
 4739	    <filename>resolver.c</filename>.
 4740	  </para>
 4741	  <para>
 4742	    The following part shows the detected final result and the
 4743	    latest result of DNSSEC validation.
 4744	    The latter is always success when no validation attempt
 4745	    is made.
 4746	    In this example, this query resulted in SERVFAIL probably
 4747	    because all name servers are down or unreachable, leading
 4748	    to a timeout in 30 seconds.
 4749	    DNSSEC validation was probably not attempted.
 4750	  </para>
 4751	  <para>
 4752	    The last part enclosed in square brackets shows statistics
 4753	    information collected for this particular resolution
 4754	    attempt.
 4755	    The <varname>domain</varname> field shows the deepest zone
 4756	    that the resolver reached;
 4757	    it is the zone where the error was finally detected.
 4758	    The meaning of the other fields is summarized in the
 4759	    following table.
 4760	  </para>
 4761
 4762          <informaltable colsep="0" rowsep="0">
 4763            <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 4764              <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/>
 4765              <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/>
 4766              <tbody>
 4767                <row rowsep="0">
 4768                  <entry colname="1">
 4769                    <para><varname>referral</varname></para>
 4770                  </entry>
 4771                  <entry colname="2">
 4772                    <para>
 4773		      The number of referrals the resolver received
 4774		      throughout the resolution process.
 4775		      In the above example this is 2, which are most
 4776		      likely com and example.com.
 4777                    </para>
 4778                  </entry>
 4779                </row>
 4780                <row rowsep="0">
 4781                  <entry colname="1">
 4782                    <para><varname>restart</varname></para>
 4783                  </entry>
 4784                  <entry colname="2">
 4785                    <para>
 4786		      The number of cycles that the resolver tried
 4787		      remote servers at the <varname>domain</varname>
 4788		      zone.
 4789		      In each cycle the resolver sends one query
 4790		      (possibly resending it, depending on the response)
 4791		      to each known name server of
 4792		      the <varname>domain</varname> zone.
 4793                    </para>
 4794                  </entry>
 4795                </row>
 4796                <row rowsep="0">
 4797                  <entry colname="1">
 4798                    <para><varname>qrysent</varname></para>
 4799                  </entry>
 4800                  <entry colname="2">
 4801                    <para>
 4802		      The number of queries the resolver sent at the
 4803		      <varname>domain</varname> zone.
 4804                    </para>
 4805                  </entry>
 4806                </row>
 4807                <row rowsep="0">
 4808                  <entry colname="1">
 4809                    <para><varname>timeout</varname></para>
 4810                  </entry>
 4811                  <entry colname="2">
 4812                    <para>
 4813		      The number of timeouts since the resolver
 4814		      received the last response.
 4815		    </para>
 4816		  </entry>
 4817		</row>
 4818                <row rowsep="0">
 4819                  <entry colname="1">
 4820                    <para><varname>lame</varname></para>
 4821                  </entry>
 4822                  <entry colname="2">
 4823                    <para>
 4824		      The number of lame servers the resolver detected
 4825		      at the <varname>domain</varname> zone.
 4826		      A server is detected to be lame either by an
 4827		      invalid response or as a result of lookup in
 4828		      BIND9's address database (ADB), where lame
 4829		      servers are cached.
 4830		    </para>
 4831		  </entry>
 4832		</row>
 4833                <row rowsep="0">
 4834                  <entry colname="1">
 4835                    <para><varname>neterr</varname></para>
 4836                  </entry>
 4837                  <entry colname="2">
 4838                    <para>
 4839		      The number of erroneous results that the
 4840		      resolver encountered in sending queries
 4841		      at the <varname>domain</varname> zone.
 4842		      One common case is the remote server is
 4843		      unreachable and the resolver receives an ICMP
 4844		      unreachable error message.
 4845		    </para>
 4846		  </entry>
 4847		</row>
 4848                <row rowsep="0">
 4849                  <entry colname="1">
 4850                    <para><varname>badresp</varname></para>
 4851                  </entry>
 4852                  <entry colname="2">
 4853                    <para>
 4854		      The number of unexpected responses (other than
 4855		      <varname>lame</varname>) to queries sent by the
 4856		      resolver at the <varname>domain</varname> zone.
 4857		    </para>
 4858		  </entry>
 4859		</row>
 4860                <row rowsep="0">
 4861                  <entry colname="1">
 4862                    <para><varname>adberr</varname></para>
 4863                  </entry>
 4864                  <entry colname="2">
 4865                    <para>
 4866		      Failures in finding remote server addresses
 4867		      of the <varname>domain</varname> zone in the ADB.
 4868		      One common case of this is that the remote
 4869		      server's name does not have any address records.
 4870		    </para>
 4871		  </entry>
 4872		</row>
 4873                <row rowsep="0">
 4874                  <entry colname="1">
 4875                    <para><varname>findfail</varname></para>
 4876                  </entry>
 4877                  <entry colname="2">
 4878                    <para>
 4879		      Failures of resolving remote server addresses.
 4880		      This is a total number of failures throughout
 4881		      the resolution process.
 4882		    </para>
 4883		  </entry>
 4884		</row>
 4885                <row rowsep="0">
 4886                  <entry colname="1">
 4887                    <para><varname>valfail</varname></para>
 4888                  </entry>
 4889                  <entry colname="2">
 4890                    <para>
 4891		      Failures of DNSSEC validation.
 4892		      Validation failures are counted throughout
 4893		      the resolution process (not limited to
 4894		      the <varname>domain</varname> zone), but should
 4895		      only happen in <varname>domain</varname>.
 4896		    </para>
 4897		  </entry>
 4898		</row>
 4899	      </tbody>
 4900	    </tgroup>
 4901	  </informaltable>
 4902	  <para>
 4903	    At the debug levels of 3 or higher, the same messages
 4904	    as those at the debug 1 level are logged for other errors
 4905	    than SERVFAIL.
 4906	    Note that negative responses such as NXDOMAIN are not
 4907	    regarded as errors here.
 4908	  </para>
 4909	  <para>
 4910	    At the debug levels of 4 or higher, the same messages
 4911	    as those at the debug 2 level are logged for other errors
 4912	    than SERVFAIL.
 4913	    Unlike the above case of level 3, messages are logged for
 4914	    negative responses.
 4915	    This is because any unexpected results can be difficult to
 4916	    debug in the recursion case.
 4917	  </para>
 4918	</sect3>
 4919      </sect2>
 4920
 4921      <sect2>
 4922        <title><command>lwres</command> Statement Grammar</title>
 4923
 4924        <para>
 4925           This is the grammar of the <command>lwres</command>
 4926          statement in the <filename>named.conf</filename> file:
 4927        </para>
 4928
 4929<programlisting><command>lwres</command> {
 4930    <optional> listen-on { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ;
 4931                <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional>
 4932    <optional> view <replaceable>view_name</replaceable>; </optional>
 4933    <optional> search { <replaceable>domain_name</replaceable> ; <optional> <replaceable>domain_name</replaceable> ; ... </optional> }; </optional>
 4934    <optional> ndots <replaceable>number</replaceable>; </optional>
 4935};
 4936</programlisting>
 4937
 4938      </sect2>
 4939      <sect2>
 4940        <title><command>lwres</command> Statement Definition and Usage</title>
 4941
 4942        <para>
 4943          The <command>lwres</command> statement configures the
 4944          name
 4945          server to also act as a lightweight resolver server. (See
 4946          <xref linkend="lwresd"/>.)  There may be multiple
 4947          <command>lwres</command> statements configuring
 4948          lightweight resolver servers with different properties.
 4949        </para>
 4950
 4951        <para>
 4952          The <command>listen-on</command> statement specifies a
 4953          list of
 4954          addresses (and ports) that this instance of a lightweight resolver
 4955          daemon
 4956          should accept requests on.  If no port is specified, port 921 is
 4957          used.
 4958          If this statement is omitted, requests will be accepted on
 4959          127.0.0.1,
 4960          port 921.
 4961        </para>
 4962
 4963        <para>
 4964          The <command>view</command> statement binds this
 4965          instance of a
 4966          lightweight resolver daemon to a view in the DNS namespace, so that
 4967          the
 4968          response will be constructed in the same manner as a normal DNS
 4969          query
 4970          matching this view.  If this statement is omitted, the default view
 4971          is
 4972          used, and if there is no default view, an error is triggered.
 4973        </para>
 4974
 4975        <para>
 4976          The <command>search</command> statement is equivalent to
 4977          the
 4978          <command>search</command> statement in
 4979          <filename>/etc/resolv.conf</filename>.  It provides a
 4980          list of domains
 4981          which are appended to relative names in queries.
 4982        </para>
 4983
 4984        <para>
 4985          The <command>ndots</command> statement is equivalent to
 4986          the
 4987          <command>ndots</command> statement in
 4988          <filename>/etc/resolv.conf</filename>.  It indicates the
 4989          minimum
 4990          number of dots in a relative domain name that should result in an
 4991          exact match lookup before search path elements are appended.
 4992        </para>
 4993      </sect2>
 4994      <sect2>
 4995        <title><command>masters</command> Statement Grammar</title>
 4996
 4997<programlisting>
 4998<command>masters</command> <replaceable>name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | 
 4999      <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> };
 5000</programlisting>
 5001
 5002      </sect2>
 5003
 5004      <sect2>
 5005        <title><command>masters</command> Statement Definition and
 5006          Usage</title>
 5007        <para><command>masters</command>
 5008	  lists allow for a common set of masters to be easily used by
 5009          multiple stub and slave zones.
 5010        </para>
 5011      </sect2>
 5012
 5013      <sect2>
 5014        <title><command>options</command> Statement Grammar</title>
 5015
 5016        <para>
 5017          This is the grammar of the <command>options</command>
 5018          statement in the <filename>named.conf</filename> file:
 5019        </para>
 5020
 5021<programlisting><command>options</command> {
 5022    <optional> attach-cache <replaceable>cache_name</replaceable>; </optional>
 5023    <optional> version <replaceable>version_string</replaceable>; </optional>
 5024    <optional> hostname <replaceable>hostname_string</replaceable>; </optional>
 5025    <optional> server-id <replaceable>server_id_string</replaceable>; </optional>
 5026    <optional> directory <replaceable>path_name</replaceable>; </optional>
 5027    <optional> key-directory <replaceable>path_name</replaceable>; </optional>
 5028    <optional> managed-keys-directory <replaceable>path_name</replaceable>; </optional>
 5029    <optional> named-xfer <replaceable>path_name</replaceable>; </optional>
 5030    <optional> tkey-gssapi-keytab <replaceable>path_name</replaceable>; </optional>
 5031    <optional> tkey-gssapi-credential <replaceable>principal</replaceable>; </optional>
 5032    <optional> tkey-domain <replaceable>domainname</replaceable>; </optional>
 5033    <optional> tkey-dhkey <replaceable>key_name</replaceable> <replaceable>key_tag</replaceable>; </optional>
 5034    <optional> cache-file <replaceable>path_name</replaceable>; </optional>
 5035    <optional> dump-file <replaceable>path_name</replaceable>; </optional>
 5036    <optional> bindkeys-file <replaceable>path_name</replaceable>; </optional>
 5037    <optional> secroots-file <replaceable>path_name</replaceable>; </optional>
 5038    <optional> session-keyfile <replaceable>path_name</replaceable>; </optional>
 5039    <optional> session-keyname <replaceable>key_name</replaceable>; </optional>
 5040    <optional> session-keyalg <replaceable>algorithm_id</replaceable>; </optional>
 5041    <optional> memstatistics <replaceable>yes_or_no</replaceable>; </optional>
 5042    <optional> memstatistics-file <replaceable>path_name</replaceable>; </optional>
 5043    <optional> pid-file <replaceable>path_name</replaceable>; </optional>
 5044    <optional> recursing-file <replaceable>path_name</replaceable>; </optional>
 5045    <optional> statistics-file <replaceable>path_name</replaceable>; </optional>
 5046    <optional> zone-statistics <replaceable>yes_or_no</replaceable>; </optional>
 5047    <optional> auth-nxdomain <replaceable>yes_or_no</replaceable>; </optional>
 5048    <optional> deallocate-on-exit <replaceable>yes_or_no</replaceable>; </optional>
 5049    <optional> dialup <replaceable>dialup_option</replaceable>; </optional>
 5050    <optional> fake-iquery <replaceable>yes_or_no</replaceable>; </optional>
 5051    <optional> fetch-glue <replaceable>yes_or_no</replaceable>; </optional>
 5052    <optional> flush-zones-on-shutdown <replaceable>yes_or_no</replaceable>; </optional>
 5053    <optional> has-old-clients <replaceable>yes_or_no</replaceable>; </optional>
 5054    <optional> host-statistics <replaceable>yes_or_no</replaceable>; </optional>
 5055    <optional> host-statistics-max <replaceable>number</replaceable>; </optional>
 5056    <optional> minimal-responses <replaceable>yes_or_no</replaceable>; </optional>
 5057    <optional> multiple-cnames <replaceable>yes_or_no</replaceable>; </optional>
 5058    <optional> notify <replaceable>yes_or_no</replaceable> | <replaceable>explicit</replaceable> | <replaceable>master-only</replaceable>; </optional>
 5059    <optional> recursion <replaceable>yes_or_no</replaceable>; </optional>
 5060    <optional> rfc2308-type1 <replaceable>yes_or_no</replaceable>; </optional>
 5061    <optional> use-id-pool <replaceable>yes_or_no</replaceable>; </optional>
 5062    <optional> maintain-ixfr-base <replaceable>yes_or_no</replaceable>; </optional>
 5063    <optional> ixfr-from-differences (<replaceable>yes_or_no</replaceable> | <constant>master</constant> | <constant>slave</constant>); </optional>
 5064    <optional> dnssec-enable <replaceable>yes_or_no</replaceable>; </optional>
 5065    <optional> dnssec-validation (<replaceable>yes_or_no</replaceable> | <constant>auto</constant>); </optional>
 5066    <optional> dnssec-lookaside ( <replaceable>auto</replaceable> |
 5067			<replaceable>no</replaceable> |
 5068                        <replaceable>domain</replaceable> trust-anchor <replaceable>domain</replaceable> ); </optional>
 5069    <optional> dnssec-must-be-secure <replaceable>domain yes_or_no</replaceable>; </optional>
 5070    <optional> dnssec-accept-expired <replaceable>yes_or_no</replaceable>; </optional>
 5071    <optional> forward ( <replaceable>only</replaceable> | <replaceable>first</replaceable> ); </optional>
 5072    <optional> forwarders { <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional>
 5073    <optional> dual-stack-servers <optional>port <replaceable>ip_port</replaceable></optional> {
 5074        ( <replaceable>domain_name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> |
 5075          <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ) ; 
 5076        ... }; </optional>
 5077    <optional> check-names ( <replaceable>master</replaceable> | <replaceable>slave</replaceable> | <replaceable>response</replaceable> )
 5078        ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
 5079    <optional> check-dup-records ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
 5080    <optional> check-mx ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
 5081    <optional> check-wildcard <replaceable>yes_or_no</replaceable>; </optional>
 5082    <optional> check-integrity <replaceable>yes_or_no</replaceable>; </optional>
 5083    <optional> check-mx-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
 5084    <optional> check-srv-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional>
 5085    <optional> check-sibling <replaceable>yes_or_no</replaceable>; </optional>
 5086    <optional> allow-new-zones { <replaceable>yes_or_no</replaceable> }; </optional>
 5087    <optional> allow-notify { <replaceable>address_match_list</replaceable> }; </optional>
 5088    <optional> allow-query { <replaceable>address_match_list</replaceable> }; </optional>
 5089    <optional> allow-query-on { <replaceable>address_match_list</replaceable> }; </optional>
 5090    <optional> allow-query-cache { <replaceable>address_match_list</replaceable> }; </optional>
 5091    <optional> allow-query-cache-on { <replaceable>address_match_list</replaceable> }; </optional>
 5092    <optional> allow-transfer { <replaceable>address_match_list</replaceable> }; </optional>
 5093    <optional> allow-recursion { <replaceable>address_match_list</replaceable> }; </optional>
 5094    <optional> allow-recursion-on { <replaceable>address_match_list</replaceable> }; </optional>
 5095    <optional> allow-update { <replaceable>address_match_list</replaceable> }; </optional>
 5096    <optional> allow-update-forwarding { <replaceable>address_match_list</replaceable> }; </optional>
 5097    <optional> update-check-ksk <replaceable>yes_or_no</replaceable>; </optional>
 5098    <optional> dnssec-dnskey-kskonly <replaceable>yes_or_no</replaceable>; </optional>
 5099    <optional> dnssec-secure-to-insecure <replaceable>yes_or_no</replaceable> ;</optional>
 5100    <optional> try-tcp-refresh <replaceable>yes_or_no</replaceable>; </optional>
 5101    <optional> allow-v6-synthesis { <replaceable>address_match_list</replaceable> }; </optional>
 5102    <optional> blackhole { <replaceable>address_match_list</replaceable> }; </optional>
 5103    <optional> use-v4-udp-ports { <replaceable>port_list</replaceable> }; </optional>
 5104    <optional> avoid-v4-udp-ports { <replaceable>port_list</replaceable> }; </optional>
 5105    <optional> use-v6-udp-ports { <replaceable>port_list</replaceable> }; </optional>
 5106    <optional> avoid-v6-udp-ports { <replaceable>port_list</replaceable> }; </optional>
 5107    <optional> listen-on <optional> port <replaceable>ip_port</replaceable> </optional> { <replaceable>address_match_list</replaceable> }; </optional>
 5108    <optional> listen-on-v6 <optional> port <replaceable>ip_port</replaceable> </optional> { <replaceable>address_match_list</replaceable> }; </optional>
 5109    <optional> query-source ( ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> )
 5110        <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> |
 5111        <optional> address ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) </optional>
 5112        <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional>
 5113    <optional> query-source-v6 ( ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> )
 5114        <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | 
 5115        <optional> address ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) </optional> 
 5116        <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional>
 5117    <optional> use-queryport-pool <replaceable>yes_or_no</replaceable>; </optional>
 5118    <optional> queryport-pool-ports <replaceable>number</replaceable>; </optional>
 5119    <optional> queryport-pool-updateinterval <replaceable>number</replaceable>; </optional>
 5120    <optional> max-transfer-time-in <replaceable>number</replaceable>; </optional>
 5121    <optional> max-transfer-time-out <replaceable>number</replaceable>; </optional>
 5122    <optional> max-transfer-idle-in <replaceable>number</replaceable>; </optional>
 5123    <optional> max-transfer-idle-out <replaceable>number</replaceable>; </optional>
 5124    <optional> tcp-clients <replaceable>number</replaceable>; </optional>
 5125    <optional> reserved-sockets <replaceable>number</replaceable>; </optional>
 5126    <optional> recursive-clients <replaceable>number</replaceable>; </optional>
 5127    <optional> serial-query-rate <replaceable>number</replaceable>; </optional>
 5128    <optional> serial-queries <replaceable>number</replaceable>; </optional>
 5129    <optional> tcp-listen-queue <replaceable>number</replaceable>; </optional>
 5130    <optional> transfer-format <replaceable>( one-answer | many-answers )</replaceable>; </optional>
 5131    <optional> transfers-in  <replaceable>number</replaceable>; </optional>
 5132    <optional> transfers-out <replaceable>number</replaceable>; </optional>
 5133    <optional> transfers-per-ns <replaceable>number</replaceable>; </optional>
 5134    <optional> transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5135    <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5136    <optional> alt-transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5137    <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>)
 5138                             <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5139    <optional> use-alt-transfer-source <replaceable>yes_or_no</replaceable>; </optional>
 5140    <optional> notify-delay <replaceable>seconds</replaceable> ; </optional>
 5141    <optional> notify-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5142    <optional> notify-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional>
 5143    <optional> notify-to-soa <replaceable>yes_or_no</replaceable> ; </optional>
 5144    <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ;
 5145                  <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional>
 5146    <optional> max-ixfr-log-size <replaceable>number</replaceable>; </optional>
 5147    <optional> max-journal-size <replaceable>size_spec</replaceable>; </optional>
 5148    <optional> coresize <replaceable>size_spec</replaceable> ; </optional>
 5149    <optional> datasize <replaceable>size_spec</replaceable> ; </optional>
 5150    <optional> files <replaceable>size_spec</replaceable> ; </optional>
 5151    <optional> stacksize <replaceable>size_spec</replaceable> ; </optional>
 5152    <optional> cleaning-interval <replaceable>number</replaceable>; </optional>
 5153    <optional> heartbeat-interval <replaceable>number</replaceable>; </optional>
 5154    <optional> interface-interval <replaceable>number</replaceable>; </optional>
 5155    <optional> statistics-interval <replaceable>number</replaceable>; </optional>
 5156    <optional> topology { <replaceable>address_match_list</replaceable> }</optional>;
 5157    <optional> sortlist { <replaceable>address_match_list</replaceable> }</optional>;
 5158    <optional> rrset-order { <replaceable>order_spec</replaceable> ; <optional> <replaceable>order_spec</replaceable> ; ... </optional> </optional> };
 5159    <optional> lame-ttl <replaceable>number</replaceable>; </optional>
 5160    <optional> max-ncache-ttl <replaceable>number</replaceable>; </optional>
 5161    <optional> max-cache-ttl <replaceable>number</replaceable>; </optional>
 5162    <optional> sig-validity-interval <replaceable>number</replaceable> <optional><replaceable>number</replaceable></optional> ; </optional>
 5163    <optional> sig-signing-nodes <replaceable>number</replaceable> ; </optional>
 5164    <optional> sig-signing-signatures <replaceable>number</replaceable> ; </optional>
 5165    <optional> sig-signing-type <replaceable>number</replaceable> ; </optional>
 5166    <optional> min-roots <replaceable>number</replaceable>; </optional>
 5167    <optional> use-ixfr <replaceable>yes_or_no</replaceable> ; </optional>
 5168    <optional> provide-ixfr <replaceable>yes_or_no</replaceable>; </optional>
 5169    <optional> request-ixfr <replaceable>yes_or_no</replaceable>; </optional>
 5170    <optional> treat-cr-as-space <replaceable>yes_or_no</replaceable> ; </optional>
 5171    <optional> min-refresh-time <replaceable>number</replaceable> ; </optional>
 5172    <optional> max-refresh-time <replaceable>number</replaceable> ; </optional>
 5173    <optional> min-retry-time <replaceable>number</replaceable> ; </optional>
 5174    <optional> max-retry-time <replaceable>number</replaceable> ; </optional>
 5175    <optional> port <replaceable>ip_port</replaceable>; </optional>
 5176    <optional> additional-from-auth <replaceable>yes_or_no</replaceable> ; </optional>
 5177    <optional> additional-from-cache <replaceable>yes_or_no</replaceable> ; </optional>
 5178    <optional> random-device <replaceable>path_name</replaceable> ; </optional>
 5179    <optional> max-cache-size <replaceable>size_spec</replaceable> ; </optional>
 5180    <optional> match-mapped-addresses <replaceable>yes_or_no</replaceable>; </optional>
 5181    <optional> filter-aaaa-on-v4 ( <replaceable>yes_or_no</replaceable> | <replaceable>break-dnssec</replaceable> ); </optional>
 5182    <optional> filter-aaaa { <replaceable>address_match_list</replaceable> }; </optional>
 5183    <optional> dns64 <replaceable>IPv6-prefix</replaceable> {
 5184	<optional> clients { <replaceable>address_match_list</replaceable> }; </optional>
 5185	<optional> mapped { <replaceable>address_match_list</replaceable> }; </optional>
 5186        <optional> exclude { <replaceable>address_match_list</replaceable> }; </optional>
 5187	<optional> suffix IPv6-address; </optional>
 5188	<optional> recursive-only <replaceable>yes_or_no</replaceable>; </optional>
 5189	<optional> break-dnssec <replaceable>yes_or_no</replaceable>; </optional>
 5190    }; </optional>;
 5191    <optional> dns64-server <replaceable>name</replaceable> </optional>
 5192    <optional> dns64-contact <replaceable>name</replaceable> </optional>
 5193    <optional> preferred-glue ( <replaceable>A</replaceable> | <replaceable>AAAA</replaceable> | <replaceable>NONE</replaceable> ); </optional>
 5194    <optional> edns-udp-size <replaceable>number</replaceable>; </optional>
 5195    <optional> max-udp-size <replaceable>number</replaceable>; </optional>
 5196    <optional> root-delegation-only <optional> exclude { <replaceable>namelist</replaceable> } </optional> ; </optional>
 5197    <optional> querylog <replaceable>yes_or_no</replaceable> ; </optional>
 5198    <optional> disable-algorithms <replaceable>domain</replaceable> { <replaceable>algorithm</replaceable>;
 5199                                <optional> <replaceable>algorithm</replaceable>; </optional> }; </optional>
 5200    <optional> acache-enable <replaceable>yes_or_no</replaceable> ; </optional>
 5201    <optional> acache-cleaning-interval <replaceable>number</replaceable>; </optional>
 5202    <optional> max-acache-size <replaceable>size_spec</replaceable> ; </optional>
 5203    <optional> clients-per-query <replaceable>number</replaceable> ; </optional>
 5204    <optional> max-clients-per-query <replaceable>number</replaceable> ; </optional>
 5205    <optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
 5206    <optional> empty-server <replaceable>name</replaceable> ; </optional>
 5207    <optional> empty-contact <replaceable>name</replaceable> ; </optional>
 5208    <optional> empty-zones-enable <replaceable>yes_or_no</replaceable> ; </optional>
 5209    <optional> disable-empty-zone <replaceable>zone_name</replaceable> ; </optional>
 5210    <optional> zero-no-soa-ttl <replaceable>yes_or_no</replaceable> ; </optional>
 5211    <optional> zero-no-soa-ttl-cache <replaceable>yes_or_no</replaceable> ; </optional>
 5212    <optional> resolver-query-timeout <replaceable>number</replaceable> ; </optional>
 5213    <optional> deny-answer-addresses { <replaceable>address_match_list</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional>
 5214    <optional> deny-answer-aliases { <replaceable>namelist</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional>
 5215    <optional> response-policy { <replaceable>zone_name</replaceable> <optional> policy given | disabled | passthru | nxdomain | nodata | cname <replaceable>domain</replaceable> </optional> ; } ; </optional>
 5216};
 5217</programlisting>
 5218
 5219      </sect2>
 5220
 5221      <sect2 id="options">
 5222        <title><command>options</command> Statement Definition and
 5223          Usage</title>
 5224
 5225        <para>
 5226          The <command>options</command> statement sets up global
 5227          options
 5228          to be used by <acronym>BIND</acronym>. This statement
 5229          may appear only
 5230          once in a configuration file. If there is no <command>options</command>
 5231          statement, an options block with each option set to its default will
 5232          be used.
 5233        </para>
 5234
 5235        <variablelist>
 5236
 5237            <varlistentry>
 5238              <term><command>attach-cache</command></term>
 5239              <listitem>
 5240                <para>
 5241		  Allows multiple views to share a single cache
 5242		  database.
 5243		  Each view has its own cache database by default, but
 5244		  if multiple views have the same operational policy
 5245		  for name resolution and caching, those views can
 5246		  share a single cache to save memory and possibly
 5247		  improve resolution efficiency by using this option.
 5248                </para>
 5249
 5250                <para>
 5251                  The <command>attach-cache</command> option
 5252                  may also be specified in <command>view</command>
 5253                  statements, in which case it overrides the
 5254                  global <command>attach-cache</command> option.
 5255                </para>
 5256
 5257		<para>
 5258		  The <replaceable>cache_name</replaceable> specifies
 5259		  the cache to be shared.
 5260		  When the <command>named</command> server configures
 5261		  views which are supposed to share a cache, it
 5262		  creates a cache with the specified name for the
 5263		  first view of these sharing views.
 5264		  The rest of the views will simply refer to the
 5265		  already created cache.
 5266		</para>
 5267
 5268		<para>
 5269		  One common configuration to share a cache would be to
 5270		  allow all views to share a single cache.
 5271		  This can be done by specifying
 5272		  the <command>attach-cache</command> as a global
 5273		  option with an arbitrary name.
 5274		</para>
 5275
 5276		<para>
 5277		  Another possible operation is to allow a subset of
 5278		  all views to share a cache while the others to
 5279		  retain their own caches.
 5280		  For example, if there are three views A, B, and C,
 5281		  and only A and B should share a cache, specify the
 5282		  <command>attach-cache</command> option as a view A (or
 5283		  B)'s option, referring to the other view name:
 5284		</para>
 5285
 5286<programlisting>
 5287  view "A" {
 5288    // this view has its own cache
 5289    ...
 5290  };
 5291  view "B" {
 5292    // this view refers to A's cache
 5293    attach-cache "A";
 5294  };
 5295  view "C" {
 5296    // this view has its own cache
 5297    ...
 5298  };
 5299</programlisting>
 5300
 5301		<para>
 5302		  Views that share a cache must have the same policy
 5303		  on configurable parameters that may affect caching.
 5304		  The current implementation requires the following
 5305		  configurable options be consistent among these
 5306		  views:
 5307		  <command>check-names</command>,
 5308		  <command>cleaning-interval</command>,
 5309		  <command>dnssec-accept-expired</command>,
 5310		  <command>dnssec-validation</command>,
 5311		  <command>max-cache-ttl</command>,
 5312		  <command>max-ncache-ttl</command>,
 5313		  <command>max-cache-size</command>, and
 5314		  <command>zero-no-soa-ttl</command>.
 5315		</para>
 5316
 5317		<para>
 5318		  Note that there may be other parameters that may
 5319		  cause confusion if they are inconsistent for
 5320		  different views that share a single cache.
 5321		  For example, if these views define different sets of
 5322		  forwarders that can return different answers for the
 5323		  same question, sharing the answer does not make
 5324		  sense or could even be harmful.
 5325		  It is administrator's responsibility to ensure
 5326		  configuration differences in different views do
 5327		  not cause disruption with a shared cache.
 5328		</para>
 5329              </listitem>
 5330
 5331            </varlistentry>
 5332
 5333          <varlistentry>
 5334            <term><command>directory</command></term>
 5335            <listitem>
 5336              <para>
 5337                The working directory of the server.
 5338                Any non-absolute pathnames in the configuration file will be
 5339                taken
 5340                as relative to this directory. The default location for most
 5341                server
 5342                output files (e.g. <filename>named.run</filename>)
 5343                is this directory.
 5344                If a directory is not specified, the working directory
 5345                defaults to `<filename>.</filename>', the directory from
 5346                which the server
 5347                was started. The directory specified should be an absolute
 5348                path.
 5349              </para>
 5350            </listitem>
 5351          </varlistentry>
 5352
 5353          <varlistentry>
 5354            <term><command>key-directory</command></term>
 5355            <listitem>
 5356              <para>
 5357                When performing dynamic update of secure zones, the
 5358                directory where the public and private DNSSEC key files
 5359                should be found, if different than the current working
 5360                directory.  (Note that this option has no effect on the
 5361                paths for files containing non-DNSSEC keys such as
 5362                <filename>bind.keys</filename>,
 5363                <filename>rndc.key</filename> or
 5364                <filename>session.key</filename>.)
 5365              </para>
 5366            </listitem>
 5367          </varlistentry>
 5368
 5369          <varlistentry>
 5370            <term><command>managed-keys-directory</command></term>
 5371            <listitem>
 5372              <para>
 5373		The directory used to hold the files used to track managed keys.
 5374		By default it is the working directory.  It there are no
 5375		views then the file <filename>managed-keys.bind</filename>
 5376		otherwise a SHA256 hash of the view name is used with
 5377		<filename>.mkeys</filename> extension added.
 5378              </para>
 5379            </listitem>
 5380          </varlistentry>
 5381
 5382          <varlistentry>
 5383            <term><command>named-xfer</command></term>
 5384	    <listitem>
 5385	      <para>
 5386		<emphasis>This option is obsolete.</emphasis> It
 5387		was used in <acronym>BIND</acronym> 8 to specify
 5388		the pathname to the <command>named-xfer</command>
 5389		program.  In <acronym>BIND</acronym> 9, no separate
 5390		<command>named-xfer</command> program is needed;
 5391		its functionality is built into the name server.
 5392	      </para>
 5393	    </listitem>
 5394	  </varlistentry>
 5395
 5396	  <varlistentry>
 5397	    <term><command>tkey-gssapi-keytab</command></term>
 5398	    <listitem>
 5399	      <para>
 5400		The KRB5 keytab file to use for GSS-TSIG updates. If
 5401		this option is set and tkey-gssapi-credential is not
 5402		set, then updates will be allowed with any key
 5403		matching a principal in the specified keytab.
 5404	      </para>
 5405	    </listitem>
 5406	  </varlistentry>
 5407
 5408	  <varlistentry>
 5409	    <term><command>tkey-gssapi-credential</command></term>
 5410	    <listitem>
 5411	      <para>
 5412		The security credential with which the server should
 5413		authenticate keys requested by the GSS-TSIG protocol.
 5414		Currently only Kerberos 5 authentication is available
 5415		and the credential is a Kerberos principal which the
 5416		server can acquire through the default system key
 5417		file, normally <filename>/etc/krb5.keytab</filename>.
 5418		The location keytab file can be overridden using the
 5419		tkey-gssapi-keytab option. Normally this principal is
 5420		of the form "<userinput>DNS/</userinput><varname>server.domain</varname>".
 5421		To use GSS-TSIG, <command>tkey-domain</command> must
 5422		also be set if a specific keytab is not set with
 5423		tkey-gssapi-keytab.
 5424	      </para>
 5425	    </listitem>
 5426	  </varlistentry>
 5427
 5428          <varlistentry>
 5429            <term><command>tkey-domain</command></term>
 5430	    <listitem>
 5431	      <para>
 5432		The domain appended to the names of all shared keys
 5433		generated with <command>TKEY</command>.  When a
 5434		client requests a <command>TKEY</command> exchange,
 5435		it may or may not specify the desired name for the
 5436		key. If present, the name of the shared key will
 5437		be <varname>client specified part</varname> +
 5438		<varname>tkey-domain</varname>.  Otherwise, the
 5439		name of the shared key will be <varname>random hex
 5440		digits</varname> + <varname>tkey-domain</varname>.
 5441		In most cases, the <command>domainname</command>
 5442		should be the server's domain name, or an otherwise
 5443		non-existent subdomain like
 5444		"_tkey.<varname>domainname</varname>".  If you are
 5445		using GSS-TSIG, this variable must be defined, unless
 5446		you specify a specific keytab using tkey-gssapi-keytab.
 5447	      </para>
 5448	    </listitem>
 5449	  </varlistentry>
 5450
 5451          <varlistentry>
 5452            <term><command>tkey-dhkey</command></term>
 5453            <listitem>
 5454              <para>
 5455                The Diffie-Hellman key used by the server
 5456                to generate shared keys with clients using the Diffie-Hellman
 5457                mode
 5458                of <command>TKEY</command>. The server must be
 5459                able to load the
 5460                public and private keys from files in the working directory.
 5461                In
 5462                most cases, the keyname should be the server's host name.
 5463              </para>
 5464            </listitem>
 5465          </varlistentry>
 5466
 5467          <varlistentry>
 5468            <term><command>cache-file</command></term>
 5469            <listitem>
 5470              <para>
 5471		This is for testing only.  Do not use.
 5472              </para>
 5473            </listitem>
 5474          </varlistentry>
 5475
 5476          <varlistentry>
 5477            <term><command>dump-file</command></term>
 5478            <listitem>
 5479              <para>
 5480                The pathname of the file the server dumps
 5481                the database to when instructed to do so with
 5482                <command>rndc dumpdb</command>.
 5483                If not specified, the default is <filename>named_dump.db</filename>.
 5484              </para>
 5485            </listitem>
 5486          </varlistentry>
 5487
 5488          <varlistentry>
 5489            <term><command>memstatistics-file</command></term>
 5490            <listitem>
 5491              <para>
 5492                The pathname of the file the server writes memory
 5493                usage statistics to on exit. If not specified,
 5494                the default is <filename>named.memstats</filename>.
 5495              </para>
 5496            </listitem>
 5497          </varlistentry>
 5498
 5499          <varlistentry>
 5500            <term><command>pid-file</command></term>
 5501            <listitem>
 5502              <para>
 5503                The pathname of the file the server writes its process ID
 5504                in. If not specified, the default is
 5505		<filename>/var/run/named/named.pid</filename>.
 5506                The PID file is used by programs that want to send signals to
 5507                the running
 5508                name server. Specifying <command>pid-file none</command> disables the
 5509                use of a PID file &mdash; no file will be written and any
 5510                existing one will be removed.  Note that <command>none</command>
 5511                is a keyword, not a filename, and therefore is not enclosed
 5512                in
 5513                double quotes.
 5514              </para>
 5515            </listitem>
 5516          </varlistentry>
 5517
 5518          <varlistentry>
 5519            <term><command>recursing-file</command></term>
 5520            <listitem>
 5521              <para>
 5522                The pathname of the file the server dumps
 5523                the queries that are currently recursing when instructed
 5524                to do so with <command>rndc recursing</command>.
 5525                If not specified, the default is <filename>named.recursing</filename>.
 5526              </para>
 5527            </listitem>
 5528          </varlistentry>
 5529
 5530          <varlistentry>
 5531            <term><command>statistics-file</command></term>
 5532            <listitem>
 5533              <para>
 5534                The pathname of the file the server appends statistics
 5535                to when instructed to do so using <command>rndc stats</command>.
 5536                If not specified, the default is <filename>named.stats</filename> in the
 5537                server's current directory.  The format of the file is
 5538                described
 5539                in <xref linkend="statsfile"/>.
 5540              </para>
 5541            </listitem>
 5542          </varlistentry>
 5543
 5544          <varlistentry>
 5545            <term><command>bindkeys-file</command></term>
 5546            <listitem>
 5547              <para>
 5548                The pathname of a file to override the built-in trusted
 5549		keys provided by <command>named</command>.
 5550		See the discussion of <command>dnssec-lookaside</command>
 5551                and <command>dnssec-validation</command> for details. 
 5552                If not specified, the default is
 5553		<filename>/etc/bind.keys</filename>.
 5554              </para>
 5555            </listitem>
 5556          </varlistentry>
 5557
 5558          <varlistentry>
 5559            <term><command>secroots-file</command></term>
 5560            <listitem>
 5561              <para>
 5562                The pathname of the file the server dumps
 5563                security roots to when instructed to do so with
 5564                <command>rndc secroots</command>.
 5565                If not specified, the default is
 5566		<filename>named.secroots</filename>.
 5567              </para>
 5568            </listitem>
 5569          </varlistentry>
 5570
 5571          <varlistentry>
 5572            <term><command>session-keyfile</command></term>
 5573            <listitem>
 5574              <para>
 5575                The pathname of the file into which to write a TSIG
 5576                session key generated by <command>named</command> for use by
 5577                <command>nsupdate -l</command>.  If not specified, the
 5578                default is <filename>/var/run/named/session.key</filename>.
 5579                (See <xref linkend="dynamic_update_policies"/>, and in
 5580                particular the discussion of the
 5581                <command>update-policy</command> statement's
 5582                <userinput>local</userinput> option for more
 5583                information about this feature.)
 5584              </para>
 5585            </listitem>
 5586          </varlistentry>
 5587
 5588          <varlistentry>
 5589            <term><command>session-keyname</command></term>
 5590            <listitem>
 5591              <para>
 5592                The key name to use for the TSIG session key.
 5593                If not specified, the default is "local-ddns".
 5594              </para>
 5595            </listitem>
 5596          </varlistentry>
 5597
 5598          <varlistentry>
 5599            <term><command>session-keyalg</command></term>
 5600            <listitem>
 5601              <para>
 5602                The algorithm to use for the TSIG session key.
 5603                Valid values are hmac-sha1, hmac-sha224, hmac-sha256,
 5604                hmac-sha384, hmac-sha512 and hmac-md5.  If not
 5605                specified, the default is hmac-sha256.
 5606              </para>
 5607            </listitem>
 5608          </varlistentry>
 5609
 5610          <varlistentry>
 5611            <term><command>port</command></term>
 5612            <listitem>
 5613              <para>
 5614                The UDP/TCP port number the server uses for
 5615                receiving and sending DNS protocol traffic.
 5616                The default is 53.  This option is mainly intended for server
 5617                testing;
 5618                a server using a port other than 53 will not be able to
 5619                communicate with
 5620                the global DNS.
 5621              </para>
 5622            </listitem>
 5623          </varlistentry>
 5624
 5625          <varlistentry>
 5626            <term><command>random-device</command></term>
 5627            <listitem>
 5628              <para>
 5629                The source of entropy to be used by the server.  Entropy is
 5630                primarily needed
 5631                for DNSSEC operations, such as TKEY transactions and dynamic
 5632                update of signed
 5633                zones.  This options specifies the device (or file) from which
 5634                to read
 5635                entropy.  If this is a file, operations requiring entropy will
 5636                fail when the
 5637                file has been exhausted.  If not specified, the default value
 5638                is
 5639                <filename>/dev/random</filename>
 5640                (or equivalent) when present, and none otherwise.  The
 5641                <command>random-device</command> option takes
 5642                effect during
 5643                the initial configuration load at server startup time and
 5644                is ignored on subsequent reloads.
 5645              </para>
 5646            </listitem>
 5647          </varlistentry>
 5648
 5649          <varlistentry>
 5650            <term><command>preferred-glue</command></term>
 5651            <listitem>
 5652              <para>
 5653                If specified, the listed type (A or AAAA) will be emitted
 5654                before other glue
 5655                in the additional section of a query response.
 5656                The default is not to prefer any type (NONE).
 5657              </para>
 5658            </listitem>
 5659          </varlistentry>
 5660
 5661          <varlistentry id="root_delegation_only">
 5662            <term><command>root-delegation-only</command></term>
 5663            <listitem>
 5664              <para>
 5665                Turn on enforcement of delegation-only in TLDs
 5666		(top level domains) and root zones with an optional
 5667		exclude list.
 5668              </para>
 5669	      <para>
 5670		DS queries are expected to be made to and be answered by
 5671		delegation only zones.  Such queries and responses are
 5672		treated as an exception to delegation-only processing
 5673		and are not converted to NXDOMAIN responses provided
 5674		a CNAME is not discovered at the query name.
 5675	      </para>
 5676	      <para>
 5677		If a delegation only zone server also serves a child
 5678		zone it is not always possible to determine whether
 5679		an answer comes from the delegation only zone or the
 5680		child zone.  SOA NS and DNSKEY records are apex
 5681		only records and a matching response that contains
 5682		these records or DS is treated as coming from a
 5683		child zone.  RRSIG records are also examined to see
 5684		if they are signed by a child zone or not.  The
 5685		authority section is also examined to see if there
 5686		is evidence that the answer is from the child zone.
 5687		Answers that are determined to be from a child zone
 5688		are not converted to NXDOMAIN responses.  Despite
 5689		all these checks there is still a possibility of
 5690		false negatives when a child zone is being served.
 5691	      </para>
 5692	      <para>
 5693		Similarly false positives can arise from empty nodes
 5694		(no records at the name) in the delegation only zone
 5695		when the query type is not ANY.
 5696	      </para>
 5697              <para>
 5698                Note some TLDs are not delegation only (e.g. "DE", "LV",
 5699		"US" and "MUSEUM").  This list is not exhaustive.
 5700              </para>
 5701
 5702<programlisting>
 5703options {
 5704	root-delegation-only exclude { "de"; "lv"; "us"; "museum"; };
 5705};
 5706</programlisting>
 5707
 5708            </listitem>
 5709          </varlistentry>
 5710
 5711          <varlistentry>
 5712            <term><command>disable-algorithms</command></term>
 5713            <listitem>
 5714              <para>
 5715                Disable the specified DNSSEC algorithms at and below the
 5716                specified name.
 5717                Multiple <command>disable-algorithms</command>
 5718                statements are allowed.
 5719                Only the most specific will be applied.
 5720              </para>
 5721            </listitem>
 5722          </varlistentry>
 5723
 5724          <varlistentry>
 5725            <term><command>dnssec-lookaside</command></term>
 5726            <listitem>
 5727              <para>
 5728		When set, <command>dnssec-lookaside</command> provides the
 5729		validator with an alternate method to validate DNSKEY
 5730		records at the top of a zone.  When a DNSKEY is at or
 5731		below a domain specified by the deepest
 5732		<command>dnssec-lookaside</command>, and the normal DNSSEC
 5733		validation has left the key untrusted, the trust-anchor
 5734		will be appended to the key name and a DLV record will be
 5735		looked up to see if it can validate the key.  If the DLV
 5736		record validates a DNSKEY (similarly to the way a DS
 5737                record does) the DNSKEY RRset is deemed to be trusted.
 5738	      </para>
 5739	      <para>
 5740		If <command>dnssec-lookaside</command> is set to
 5741		<userinput>auto</userinput>, then built-in default
 5742		values for the DLV domain and trust anchor will be
 5743		used, along with a built-in key for validation.
 5744	      </para>
 5745	      <para>
 5746		If <command>dnssec-lookaside</command> is set to
 5747		<userinput>no</userinput>, then dnssec-lookaside
 5748		is not used.
 5749	      </para>
 5750              <para>
 5751                The default DLV key is stored in the file
 5752                <filename>bind.keys</filename>;
 5753                <command>named</command> will load that key at
 5754                startup if <command>dnssec-lookaside</command> is set to
 5755                <constant>auto</constant>.  A copy of the file is
 5756                installed along with <acronym>BIND</acronym> 9, and is
 5757                current as of the release date.  If the DLV key expires, a
 5758                new copy of <filename>bind.keys</filename> can be downloaded
 5759                from <ulink>https://www.isc.org/solutions/dlv</ulink>.
 5760              </para>
 5761              <para>
 5762                (To prevent problems if <filename>bind.keys</filename> is
 5763                not found, the current key is also compiled in to
 5764                <command>named</command>.  Relying on this is not
 5765                recommended, however, as it requires <command>named</command>
 5766                to be recompiled with a new key when the DLV key expires.)
 5767              </para>
 5768              <para>
 5769                NOTE: <command>named</command> only loads certain specific
 5770                keys from <filename>bind.keys</filename>:  those for the
 5771                DLV zone and for the DNS root zone.  The file cannot be
 5772                used to store keys for other zones.
 5773              </para>
 5774            </listitem>
 5775          </varlistentry>
 5776
 5777          <varlistentry>
 5778            <term><command>dnssec-must-be-secure</command></term>
 5779            <listitem>
 5780              <para>
 5781                Specify hierarchies which must be or may not be secure
 5782                (signed and validated).  If <userinput>yes</userinput>,
 5783                then <command>named</command> will only accept answers if
 5784                they are secure.  If <userinput>no</userinput>, then normal
 5785                DNSSEC validation applies allowing for insecure answers to
 5786                be accepted.  The specified domain must be under a
 5787                <command>trusted-keys</command> or
 5788                <command>managed-keys</command> statement, or
 5789                <command>dnssec-lookaside</command> must be active.
 5790              </para>
 5791            </listitem>
 5792          </varlistentry>
 5793
 5794	  <varlistentry>
 5795	    <term><command>dns64</command></term>
 5796            <listitem>
 5797	      <para>
 5798		This directive instructs <command>named</command> to
 5799		return mapped IPv4 addresses to AAAA queries when
 5800		there are no AAAA records.  It is intended to be
 5801		used in conjunction with a NAT64.  Each
 5802		<command>dns64</command> defines one DNS64 prefix.
 5803		Multiple DNS64 prefixes can be defined.
 5804	      </para>
 5805	      <para>
 5806		Compatible IPv6 prefixes have lengths of 32, 40, 48, 56,
 5807		64 and 96 as per RFC 6052.
 5808	      </para>
 5809	      <para>
 5810		Additionally a reverse IP6.ARPA zone will be created for
 5811		the prefix to provide a mapping from the IP6.ARPA names
 5812		to the corresponding IN-ADDR.ARPA names using synthesized
 5813		CNAMEs.  <command>dns64-server</command> and
 5814		<command>dns64-contact</command> can be used to specify
 5815		the name of the server and contact for the zones. These
 5816		are settable at the view / options level.  These are
 5817		not settable on a per-prefix basis.
 5818	      </para>
 5819	      <para>
 5820		Each <command>dns64</command> supports an optional
 5821		<command>clients</command> ACL that determines which
 5822                clients are affected by this directive.  If not defined,
 5823                it defaults to <userinput>any;</userinput>.
 5824	      </para>
 5825	      <para>
 5826		Each <command>dns64</command> supports an optional
 5827		<command>mapped</command> ACL that selects which
 5828		IPv4 addresses are to be mapped in the corresponding	
 5829		A RRset.  If not defined it defaults to
 5830		<userinput>any;</userinput>.
 5831	      </para>
 5832	      <para>
 5833		Normally, DNS64 won't apply to a domain name that
 5834		owns one or more AAAA records; these records will
 5835		simply be returned.  The optional
 5836		<command>exclude</command> ACL allows specification
 5837		of a list of IPv6 addresses that will be ignored
 5838		if they appear in a domain name's AAAA records, and
 5839		DNS64 will be applied to any A records the domain
 5840		name owns.  If not defined, <command>exclude</command>
 5841		defaults to none.
 5842	      </para>
 5843	      <para>
 5844		A optional <command>suffix</command> can also
 5845		be defined to set the bits trailing the mapped
 5846		IPv4 address bits.  By default these bits are
 5847		set to <userinput>::</userinput>.  The bits
 5848		matching the prefix and mapped IPv4 address
 5849		must be zero.
 5850	      </para>
 5851	      <para>
 5852		If <command>recursive-only</command> is set to
 5853		<command>yes</command> the DNS64 synthesis will
 5854		only happen for recursive queries.  The default
 5855		is <command>no</command>.
 5856	      </para>
 5857	      <para>
 5858		If <command>break-dnssec</command> is set to
 5859		<command>yes</command> the DNS64 synthesis will
 5860		happen even if the result, if validated, would
 5861		cause a DNSSEC validation failure.  If this option
 5862		is set to <command>no</command> (the default), the DO
 5863		is set on the incoming query, and there are RRSIGs on
 5864		the applicable records, then synthesis will not happen.
 5865	      </para>
 5866<programlisting>
 5867	acl rfc1918 { 10/8; 192.168/16; 172.16/12; };
 5868
 5869        dns64 64:FF9B::/96 {
 5870                clients { any; };
 5871                mapped { !rfc1918; any; };
 5872                exclude { 64:FF9B::/96; ::ffff:0000:0000/96; };
 5873                suffix ::;
 5874        };
 5875</programlisting>
 5876            </listitem>
 5877	  </varlistentry>
 5878
 5879        </variablelist>
 5880
 5881        <sect3 id="boolean_options">
 5882          <title>Boolean Options</title>
 5883
 5884          <variablelist>
 5885
 5886            <varlistentry>
 5887              <term><command>allow-new-zones</command></term>
 5888              <listitem>
 5889                <para>
 5890                  If <userinput>yes</userinput>, then zones can be
 5891                  added at runtime via <command>rndc addzone</command>
 5892                  or deleted via <command>rndc delzone</command>.
 5893                  The default is <userinput>no</userinput>.
 5894                </para>
 5895              </listitem>
 5896            </varlistentry>
 5897
 5898            <varlistentry>
 5899              <term><command>auth-nxdomain</command></term>
 5900              <listitem>
 5901                <para>
 5902                  If <userinput>yes</userinput>, then the <command>AA</command> bit
 5903                  is always set on NXDOMAIN responses, even if the server is
 5904                  not actually
 5905                  authoritative. The default is <userinput>no</userinput>;
 5906                  this is
 5907                  a change from <acronym>BIND</acronym> 8. If you
 5908                  are using very old DNS software, you
 5909                  may need to set it to <userinput>yes</userinput>.
 5910                </para>
 5911              </listitem>
 5912            </varlistentry>
 5913
 5914            <varlistentry>
 5915              <term><command>deallocate-on-exit</command></term>
 5916              <listitem>
 5917                <para>
 5918                  This option was used in <acronym>BIND</acronym>
 5919                  8 to enable checking
 5920                  for memory leaks on exit. <acronym>BIND</acronym> 9 ignores the option and always performs
 5921                  the checks.
 5922                </para>
 5923              </listitem>
 5924            </varlistentry>
 5925
 5926            <varlistentry>
 5927              <term><command>memstatistics</command></term>
 5928              <listitem>
 5929                <para>
 5930		  Write memory statistics to the file specified by
 5931		  <command>memstatistics-file</command> at exit.
 5932		  The default is <userinput>no</userinput> unless
 5933		  '-m record' is specified on the command line in
 5934		  which case it is <userinput>yes</userinput>.
 5935                </para>
 5936              </listitem>
 5937            </varlistentry>
 5938
 5939            <varlistentry>
 5940              <term><command>dialup</command></term>
 5941              <listitem>
 5942                <para>
 5943                  If <userinput>yes</userinput>, then the
 5944                  server treats all zones as if they are doing zone transfers
 5945                  across
 5946                  a dial-on-demand dialup link, which can be brought up by
 5947                  traffic
 5948                  originating from this server. This has different effects
 5949                  according
 5950                  to zone type and concentrates the zone maintenance so that
 5951                  it all
 5952                  happens in a short interval, once every <command>heartbeat-interval</command> and
 5953                  hopefully during the one call. It also suppresses some of
 5954                  the normal
 5955                  zone maintenance traffic. The default is <userinput>no</userinput>.
 5956                </para>
 5957                <para>
 5958                  The <command>dialup</command> option
 5959                  may also be specified in the <command>view</command> and
 5960                  <command>zone</command> statements,
 5961                  in which case it overrides the global <command>dialup</command>
 5962                  option.
 5963                </para>
 5964                <para>
 5965                  If the zone is a master zone, then the server will send out a
 5966                  NOTIFY
 5967                  request to all the slaves (default). This should trigger the
 5968                  zone serial
 5969                  number check in the slave (providing it supports NOTIFY)
 5970                  allowing the slave
 5971                  to verify the zone while the connection is active.
 5972                  The set of servers to which NOTIFY is sent can be controlled
 5973                  by
 5974                  <command>notify</command> and <command>also-notify</command>.
 5975                </para>
 5976                <para>
 5977                  If the
 5978                  zone is a slave or stub zone, then the server will suppress
 5979                  the regular
 5980                  "zone up to date" (refresh) queries and only perform them
 5981                  when the
 5982                  <command>heartbeat-interval</command> expires in
 5983                  addition to sending
 5984                  NOTIFY requests.
 5985                </para>
 5986                <para>
 5987                  Finer control can be achieved by using
 5988                  <userinput>notify</userinput> which only sends NOTIFY
 5989                  messages,
 5990                  <userinput>notify-passive</userinput> which sends NOTIFY
 5991                  messages and
 5992                  suppresses the normal refresh queries, <userinput>refresh</userinput>
 5993                  which suppresses normal refresh processing and sends refresh
 5994                  queries
 5995                  when the <command>heartbeat-interval</command>
 5996                  expires, and
 5997                  <userinput>passive</userinput> which just disables normal
 5998                  refresh
 5999                  processing.
 6000                </para>
 6001
 6002                <informaltable colsep="0" rowsep="0">
 6003                  <tgroup cols="4" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 6004                    <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/>
 6005                    <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/>
 6006                    <colspec colname="3" colnum="3" colsep="0" colwidth="1.150in"/>
 6007                    <colspec colname="4" colnum="4" colsep="0" colwidth="1.150in"/>
 6008                    <tbody>
 6009                      <row rowsep="0">
 6010                        <entry colname="1">
 6011                          <para>
 6012                            dialup mode
 6013                          </para>
 6014                        </entry>
 6015                        <entry colname="2">
 6016                          <para>
 6017                            normal refresh
 6018                          </para>
 6019                        </entry>
 6020                        <entry colname="3">
 6021                          <para>
 6022                            heart-beat refresh
 6023                          </para>
 6024                        </entry>
 6025                        <entry colname="4">
 6026                          <para>
 6027                            heart-beat notify
 6028                          </para>
 6029                        </entry>
 6030                      </row>
 6031                      <row rowsep="0">
 6032                        <entry colname="1">
 6033                          <para><command>no</command> (default)</para>
 6034                        </entry>
 6035                        <entry colname="2">
 6036                          <para>
 6037                            yes
 6038                          </para>
 6039                        </entry>
 6040                        <entry colname="3">
 6041                          <para>
 6042                            no
 6043                          </para>
 6044                        </entry>
 6045                        <entry colname="4">
 6046                          <para>
 6047                            no
 6048                          </para>
 6049                        </entry>
 6050                      </row>
 6051                      <row rowsep="0">
 6052                        <entry colname="1">
 6053                          <para><command>yes</command></para>
 6054                        </entry>
 6055                        <entry colname="2">
 6056                          <para>
 6057                            no
 6058                          </para>
 6059                        </entry>
 6060                        <entry colname="3">
 6061                          <para>
 6062                            yes
 6063                          </para>
 6064                        </entry>
 6065                        <entry colname="4">
 6066                          <para>
 6067                            yes
 6068                          </para>
 6069                        </entry>
 6070                      </row>
 6071                      <row rowsep="0">
 6072                        <entry colname="1">
 6073                          <para><command>notify</command></para>
 6074                        </entry>
 6075                        <entry colname="2">
 6076                          <para>
 6077                            yes
 6078                          </para>
 6079                        </entry>
 6080                        <entry colname="3">
 6081                          <para>
 6082                            no
 6083                          </para>
 6084                        </entry>
 6085                        <entry colname="4">
 6086                          <para>
 6087                            yes
 6088                          </para>
 6089                        </entry>
 6090                      </row>
 6091                      <row rowsep="0">
 6092                        <entry colname="1">
 6093                          <para><command>refresh</command></para>
 6094                        </entry>
 6095                        <entry colname="2">
 6096                          <para>
 6097                            no
 6098                          </para>
 6099                        </entry>
 6100                        <entry colname="3">
 6101                          <para>
 6102                            yes
 6103                          </para>
 6104                        </entry>
 6105                        <entry colname="4">
 6106                          <para>
 6107                            no
 6108                          </para>
 6109                        </entry>
 6110                      </row>
 6111                      <row rowsep="0">
 6112                        <entry colname="1">
 6113                          <para><command>passive</command></para>
 6114                        </entry>
 6115                        <entry colname="2">
 6116                          <para>
 6117                            no
 6118                          </para>
 6119                        </entry>
 6120                        <entry colname="3">
 6121                          <para>
 6122                            no
 6123                          </para>
 6124                        </entry>
 6125                        <entry colname="4">
 6126                          <para>
 6127                            no
 6128                          </para>
 6129                        </entry>
 6130                      </row>
 6131                      <row rowsep="0">
 6132                        <entry colname="1">
 6133                          <para><command>notify-passive</command></para>
 6134                        </entry>
 6135                        <entry colname="2">
 6136                          <para>
 6137                            no
 6138                          </para>
 6139                        </entry>
 6140                        <entry colname="3">
 6141                          <para>
 6142                            no
 6143                          </para>
 6144                        </entry>
 6145                        <entry colname="4">
 6146                          <para>
 6147                            yes
 6148                          </para>
 6149                        </entry>
 6150                      </row>
 6151                    </tbody>
 6152                  </tgroup>
 6153                </informaltable>
 6154
 6155                <para>
 6156                  Note that normal NOTIFY processing is not affected by
 6157                  <command>dialup</command>.
 6158                </para>
 6159
 6160              </listitem>
 6161            </varlistentry>
 6162
 6163            <varlistentry>
 6164              <term><command>fake-iquery</command></term>
 6165              <listitem>
 6166                <para>
 6167                  In <acronym>BIND</acronym> 8, this option
 6168                  enabled simulating the obsolete DNS query type
 6169                  IQUERY. <acronym>BIND</acronym> 9 never does
 6170                  IQUERY simulation.
 6171                </para>
 6172              </listitem>
 6173            </varlistentry>
 6174
 6175            <varlistentry>
 6176              <term><command>fetch-glue</command></term>
 6177              <listitem>
 6178                <para>
 6179                  This option is obsolete.
 6180                  In BIND 8, <userinput>fetch-glue yes</userinput>
 6181                  caused the server to attempt to fetch glue resource records
 6182                  it
 6183                  didn't have when constructing the additional
 6184                  data section of a response.  This is now considered a bad
 6185                  idea
 6186                  and BIND 9 never does it.
 6187                </para>
 6188              </listitem>
 6189            </varlistentry>
 6190
 6191            <varlistentry>
 6192              <term><command>flush-zones-on-shutdown</command></term>
 6193              <listitem>
 6194                <para>
 6195                  When the nameserver exits due receiving SIGTERM,
 6196                  flush or do not flush any pending zone writes.  The default
 6197                  is
 6198                  <command>flush-zones-on-shutdown</command> <userinput>no</userinput>.
 6199                </para>
 6200              </listitem>
 6201            </varlistentry>
 6202
 6203            <varlistentry>
 6204              <term><command>has-old-clients</command></term>
 6205              <listitem>
 6206                <para>
 6207                  This option was incorrectly implemented
 6208                  in <acronym>BIND</acronym> 8, and is ignored by <acronym>BIND</acronym> 9.
 6209                  To achieve the intended effect
 6210                  of
 6211                  <command>has-old-clients</command> <userinput>yes</userinput>, specify
 6212                  the two separate options <command>auth-nxdomain</command> <userinput>yes</userinput>
 6213                  and <command>rfc2308-type1</command> <userinput>no</userinput> instead.
 6214                </para>
 6215              </listitem>
 6216            </varlistentry>
 6217
 6218            <varlistentry>
 6219              <term><command>host-statistics</command></term>
 6220              <listitem>
 6221                <para>
 6222                  In BIND 8, this enables keeping of
 6223                  statistics for every host that the name server interacts
 6224                  with.
 6225                  Not implemented in BIND 9.
 6226                </para>
 6227              </listitem>
 6228            </varlistentry>
 6229
 6230            <varlistentry>
 6231              <term><command>maintain-ixfr-base</command></term>
 6232              <listitem>
 6233                <para>
 6234                  <emphasis>This option is obsolete</emphasis>.
 6235                  It was used in <acronym>BIND</acronym> 8 to
 6236                  determine whether a transaction log was
 6237                  kept for Incremental Zone Transfer. <acronym>BIND</acronym> 9 maintains a transaction
 6238                  log whenever possible.  If you need to disable outgoing
 6239                  incremental zone
 6240                  transfers, use <command>provide-ixfr</command> <userinput>no</userinput>.
 6241                </para>
 6242              </listitem>
 6243            </varlistentry>
 6244
 6245            <varlistentry>
 6246              <term><command>minimal-responses</command></term>
 6247              <listitem>
 6248                <para>
 6249                  If <userinput>yes</userinput>, then when generating
 6250                  responses the server will only add records to the authority
 6251                  and additional data sections when they are required (e.g.
 6252                  delegations, negative responses).  This may improve the
 6253		  performance of the server.
 6254                  The default is <userinput>no</userinput>.
 6255                </para>
 6256              </listitem>
 6257            </varlistentry>
 6258
 6259            <varlistentry>
 6260              <term><command>multiple-cnames</command></term>
 6261              <listitem>
 6262                <para>
 6263                  This option was used in <acronym>BIND</acronym> 8 to allow
 6264                  a domain name to have multiple CNAME records in violation of
 6265                  the DNS standards.  <acronym>BIND</acronym> 9.2 onwards
 6266                  always strictly enforces the CNAME rules both in master
 6267		  files and dynamic updates.
 6268                </para>
 6269              </listitem>
 6270            </varlistentry>
 6271
 6272            <varlistentry>
 6273              <term><command>notify</command></term>
 6274              <listitem>
 6275                <para>
 6276                  If <userinput>yes</userinput> (the default),
 6277                  DNS NOTIFY messages are sent when a zone the server is
 6278                  authoritative for
 6279                  changes, see <xref linkend="notify"/>.  The messages are
 6280                  sent to the
 6281                  servers listed in the zone's NS records (except the master
 6282                  server identified
 6283                  in the SOA MNAME field), and to any servers listed in the
 6284                  <command>also-notify</command> option.
 6285                </para>
 6286                <para>
 6287                  If <userinput>master-only</userinput>, notifies are only
 6288                  sent
 6289                  for master zones.
 6290                  If <userinput>explicit</userinput>, notifies are sent only
 6291                  to
 6292                  servers explicitly listed using <command>also-notify</command>.
 6293                  If <userinput>no</userinput>, no notifies are sent.
 6294                </para>
 6295                <para>
 6296                  The <command>notify</command> option may also be
 6297                  specified in the <command>zone</command>
 6298                  statement,
 6299                  in which case it overrides the <command>options notify</command> statement.
 6300                  It would only be necessary to turn off this option if it
 6301                  caused slaves
 6302                  to crash.
 6303                </para>
 6304              </listitem>
 6305            </varlistentry>
 6306
 6307            <varlistentry>
 6308              <term><command>notify-to-soa</command></term>
 6309              <listitem>
 6310                <para>
 6311		  If <userinput>yes</userinput> do not check the nameservers
 6312		  in the NS RRset against the SOA MNAME.  Normally a NOTIFY
 6313		  message is not sent to the SOA MNAME (SOA ORIGIN) as it is
 6314		  supposed to contain the name of the ultimate master.
 6315		  Sometimes, however, a slave is listed as the SOA MNAME in
 6316		  hidden master configurations and in that case you would
 6317		  want the ultimate master to still send NOTIFY messages to
 6318		  all the nameservers listed in the NS RRset.
 6319                </para>
 6320              </listitem>
 6321            </varlistentry>
 6322
 6323            <varlistentry>
 6324              <term><command>recursion</command></term>
 6325              <listitem>
 6326                <para>
 6327                  If <userinput>yes</userinput>, and a
 6328                  DNS query requests recursion, then the server will attempt
 6329                  to do
 6330                  all the work required to answer the query. If recursion is
 6331                  off
 6332                  and the server does not already know the answer, it will
 6333                  return a
 6334                  referral response. The default is
 6335                  <userinput>yes</userinput>.
 6336                  Note that setting <command>recursion no</command> does not prevent
 6337                  clients from getting data from the server's cache; it only
 6338                  prevents new data from being cached as an effect of client
 6339                  queries.
 6340                  Caching may still occur as an effect the server's internal
 6341                  operation, such as NOTIFY address lookups.
 6342                  See also <command>fetch-glue</command> above.
 6343                </para>
 6344              </listitem>
 6345            </varlistentry>
 6346
 6347            <varlistentry>
 6348              <term><command>rfc2308-type1</command></term>
 6349              <listitem>
 6350                <para>
 6351                  Setting this to <userinput>yes</userinput> will
 6352                  cause the server to send NS records along with the SOA
 6353                  record for negative
 6354                  answers. The default is <userinput>no</userinput>.
 6355                </para>
 6356                <note>
 6357                  <simpara>
 6358                    Not yet implemented in <acronym>BIND</acronym>
 6359                    9.
 6360                  </simpara>
 6361                </note>
 6362              </listitem>
 6363            </varlistentry>
 6364
 6365            <varlistentry>
 6366              <term><command>use-id-pool</command></term>
 6367              <listitem>
 6368                <para>
 6369                  <emphasis>This option is obsolete</emphasis>.
 6370                  <acronym>BIND</acronym> 9 always allocates query
 6371                  IDs from a pool.
 6372                </para>
 6373              </listitem>
 6374            </varlistentry>
 6375
 6376            <varlistentry>
 6377              <term><command>zone-statistics</command></term>
 6378              <listitem>
 6379                <para>
 6380                  If <userinput>yes</userinput>, the server will collect
 6381                  statistical data on all zones (unless specifically turned
 6382                  off
 6383                  on a per-zone basis by specifying <command>zone-statistics no</command>
 6384                  in the <command>zone</command> statement).
 6385                  The default is <userinput>no</userinput>.
 6386                  These statistics may be accessed
 6387                  using <command>rndc stats</command>, which will
 6388                  dump them to the file listed
 6389                  in the <command>statistics-file</command>.  See
 6390                  also <xref linkend="statsfile"/>.
 6391                </para>
 6392              </listitem>
 6393            </varlistentry>
 6394
 6395            <varlistentry>
 6396              <term><command>use-ixfr</command></term>
 6397              <listitem>
 6398                <para>
 6399                  <emphasis>This option is obsolete</emphasis>.
 6400                  If you need to disable IXFR to a particular server or
 6401                  servers, see
 6402                  the information on the <command>provide-ixfr</command> option
 6403                  in <xref linkend="server_statement_definition_and_usage"/>.
 6404                  See also
 6405                  <xref linkend="incremental_zone_transfers"/>.
 6406                </para>
 6407              </listitem>
 6408            </varlistentry>
 6409
 6410            <varlistentry>
 6411              <term><command>provide-ixfr</command></term>
 6412              <listitem>
 6413                <para>
 6414                  See the description of
 6415                  <command>provide-ixfr</command> in
 6416                  <xref linkend="server_statement_definition_and_usage"/>.
 6417                </para>
 6418              </listitem>
 6419            </varlistentry>
 6420
 6421            <varlistentry>
 6422              <term><command>request-ixfr</command></term>
 6423              <listitem>
 6424                <para>
 6425                  See the description of
 6426                  <command>request-ixfr</command> in
 6427                  <xref linkend="server_statement_definition_and_usage"/>.
 6428                </para>
 6429              </listitem>
 6430            </varlistentry>
 6431
 6432            <varlistentry>
 6433              <term><command>treat-cr-as-space</command></term>
 6434              <listitem>
 6435                <para>
 6436                  This option was used in <acronym>BIND</acronym>
 6437                  8 to make
 6438                  the server treat carriage return ("<command>\r</command>") characters the same way
 6439                  as a space or tab character,
 6440                  to facilitate loading of zone files on a UNIX system that
 6441                  were generated
 6442                  on an NT or DOS machine. In <acronym>BIND</acronym> 9, both UNIX "<command>\n</command>"
 6443                  and NT/DOS "<command>\r\n</command>" newlines
 6444                  are always accepted,
 6445                  and the option is ignored.
 6446                </para>
 6447              </listitem>
 6448            </varlistentry>
 6449
 6450            <varlistentry>
 6451              <term><command>additional-from-auth</command></term>
 6452              <term><command>additional-from-cache</command></term>
 6453              <listitem>
 6454
 6455                <para>
 6456                  These options control the behavior of an authoritative
 6457                  server when
 6458                  answering queries which have additional data, or when
 6459                  following CNAME
 6460                  and DNAME chains.
 6461                </para>
 6462
 6463                <para>
 6464                  When both of these options are set to <userinput>yes</userinput>
 6465                  (the default) and a
 6466                  query is being answered from authoritative data (a zone
 6467                  configured into the server), the additional data section of
 6468                  the
 6469                  reply will be filled in using data from other authoritative
 6470                  zones
 6471                  and from the cache.  In some situations this is undesirable,
 6472                  such
 6473                  as when there is concern over the correctness of the cache,
 6474                  or
 6475                  in servers where slave zones may be added and modified by
 6476                  untrusted third parties.  Also, avoiding
 6477                  the search for this additional data will speed up server
 6478                  operations
 6479                  at the possible expense of additional queries to resolve
 6480                  what would
 6481                  otherwise be provided in the additional section.
 6482                </para>
 6483
 6484                <para>
 6485                  For example, if a query asks for an MX record for host <literal>foo.example.com</literal>,
 6486                  and the record found is "<literal>MX 10 mail.example.net</literal>", normally the address
 6487                  records (A and AAAA) for <literal>mail.example.net</literal> will be provided as well,
 6488                  if known, even though they are not in the example.com zone.
 6489                  Setting these options to <command>no</command>
 6490                  disables this behavior and makes
 6491                  the server only search for additional data in the zone it
 6492                  answers from.
 6493                </para>
 6494
 6495                <para>
 6496                  These options are intended for use in authoritative-only
 6497                  servers, or in authoritative-only views.  Attempts to set
 6498                  them to <command>no</command> without also
 6499                  specifying
 6500                  <command>recursion no</command> will cause the
 6501                  server to
 6502                  ignore the options and log a warning message.
 6503                </para>
 6504
 6505                <para>
 6506                  Specifying <command>additional-from-cache no</command> actually
 6507                  disables the use of the cache not only for additional data
 6508                  lookups
 6509                  but also when looking up the answer.  This is usually the
 6510                  desired
 6511                  behavior in an authoritative-only server where the
 6512                  correctness of
 6513                  the cached data is an issue.
 6514                </para>
 6515
 6516                <para>
 6517                  When a name server is non-recursively queried for a name
 6518                  that is not
 6519                  below the apex of any served zone, it normally answers with
 6520                  an
 6521                  "upwards referral" to the root servers or the servers of
 6522                  some other
 6523                  known parent of the query name.  Since the data in an
 6524                  upwards referral
 6525                  comes from the cache, the server will not be able to provide
 6526                  upwards
 6527                  referrals when <command>additional-from-cache no</command>
 6528                  has been specified.  Instead, it will respond to such
 6529                  queries
 6530                  with REFUSED.  This should not cause any problems since
 6531                  upwards referrals are not required for the resolution
 6532                  process.
 6533                </para>
 6534
 6535              </listitem>
 6536            </varlistentry>
 6537
 6538            <varlistentry>
 6539              <term><command>match-mapped-addresses</command></term>
 6540              <listitem>
 6541                <para>
 6542                  If <userinput>yes</userinput>, then an
 6543                  IPv4-mapped IPv6 address will match any address match
 6544                  list entries that match the corresponding IPv4 address.
 6545                </para>
 6546                <para>
 6547                  This option was introduced to work around a kernel quirk
 6548                  in some operating systems that causes IPv4 TCP
 6549                  connections, such as zone transfers, to be accepted on an
 6550                  IPv6 socket using mapped addresses.  This caused address
 6551                  match lists designed for IPv4 to fail to match.  However,
 6552                  <command>named</command> now solves this problem
 6553                  internally.  The use of this option is discouraged.
 6554                </para>
 6555              </listitem>
 6556            </varlistentry>
 6557
 6558            <varlistentry>
 6559              <term><command>filter-aaaa-on-v4</command></term>
 6560              <listitem>
 6561                <para>
 6562                  This option is only available when
 6563                  <acronym>BIND</acronym> 9 is compiled with the
 6564                  <userinput>--enable-filter-aaaa</userinput> option on the
 6565                  "configure" command line.  It is intended to help the
 6566                  transition from IPv4 to IPv6 by not giving IPv6 addresses
 6567                  to DNS clients unless they have connections to the IPv6
 6568                  Internet.  This is not recommended unless absolutely
 6569                  necessary.  The default is <userinput>no</userinput>.
 6570                  The <command>filter-aaaa-on-v4</command> option
 6571                  may also be specified in <command>view</command> statements
 6572                  to override the global <command>filter-aaaa-on-v4</command>
 6573                  option.
 6574                </para>
 6575                <para>
 6576                  If <userinput>yes</userinput>,
 6577                  the DNS client is at an IPv4 address, in <command>filter-aaaa</command>,
 6578                  and if the response does not include DNSSEC signatures, 
 6579                  then all AAAA records are deleted from the response.
 6580                  This filtering applies to all responses and not only
 6581                  authoritative responses.
 6582                </para>
 6583                <para>
 6584                  If <userinput>break-dnssec</userinput>,
 6585                  then AAAA records are deleted even when dnssec is enabled.
 6586                  As suggested by the name, this makes the response not verify,
 6587                  because the DNSSEC protocol is designed detect deletions.
 6588                </para>
 6589                <para>
 6590                  This mechanism can erroneously cause other servers to 
 6591		  not give AAAA records to their clients.  
 6592		  A recursing server with both IPv6 and IPv4 network connections
 6593		  that queries an authoritative server using this mechanism
 6594		  via IPv4 will be denied AAAA records even if its client is
 6595		  using IPv6.
 6596                </para>
 6597                <para>
 6598                  This mechanism is applied to authoritative as well as
 6599		  non-authoritative records.
 6600		  A client using IPv4 that is not allowed recursion can
 6601		  erroneously be given AAAA records because the server is not
 6602		  allowed to check for A records.
 6603                </para>
 6604                <para>
 6605		  Some AAAA records are given to IPv4 clients in glue records.
 6606		  IPv4 clients that are servers can then erroneously
 6607		  answer requests for AAAA records received via IPv4.
 6608                </para>
 6609              </listitem>
 6610            </varlistentry>
 6611
 6612            <varlistentry>
 6613              <term><command>ixfr-from-differences</command></term>
 6614              <listitem>
 6615                <para>
 6616                  When <userinput>yes</userinput> and the server loads a new version of a master
 6617                  zone from its zone file or receives a new version of a slave
 6618                  file by a non-incremental zone transfer, it will compare
 6619                  the new version to the previous one and calculate a set
 6620                  of differences.  The differences are then logged in the
 6621                  zone's journal file such that the changes can be transmitted
 6622                  to downstream slaves as an incremental zone transfer.
 6623                </para>
 6624                <para>
 6625                  By allowing incremental zone transfers to be used for
 6626                  non-dynamic zones, this option saves bandwidth at the
 6627                  expense of increased CPU and memory consumption at the
 6628                  master.
 6629                  In particular, if the new version of a zone is completely
 6630                  different from the previous one, the set of differences
 6631                  will be of a size comparable to the combined size of the
 6632                  old and new zone version, and the server will need to
 6633                  temporarily allocate memory to hold this complete
 6634                  difference set.
 6635                </para>
 6636                <para><command>ixfr-from-differences</command>
 6637		  also accepts <command>master</command> and
 6638                  <command>slave</command> at the view and options
 6639                  levels which causes
 6640                  <command>ixfr-from-differences</command> to be enabled for
 6641                  all <command>master</command> or
 6642                  <command>slave</command> zones respectively.
 6643                  It is off by default.
 6644                </para>
 6645              </listitem>
 6646            </varlistentry>
 6647
 6648            <varlistentry>
 6649              <term><command>multi-master</command></term>
 6650              <listitem>
 6651                <para>
 6652                  This should be set when you have multiple masters for a zone
 6653                  and the
 6654                  addresses refer to different machines.  If <userinput>yes</userinput>, <command>named</command> will
 6655                  not log
 6656                  when the serial number on the master is less than what <command>named</command>
 6657                  currently
 6658                  has.  The default is <userinput>no</userinput>.
 6659                </para>
 6660              </listitem>
 6661            </varlistentry>
 6662
 6663            <varlistentry>
 6664              <term><command>dnssec-enable</command></term>
 6665              <listitem>
 6666                <para>
 6667                  Enable DNSSEC support in <command>named</command>.  Unless set to <userinput>yes</userinput>,
 6668                  <command>named</command> behaves as if it does not support DNSSEC.
 6669                  The default is <userinput>yes</userinput>.
 6670                </para>
 6671              </listitem>
 6672            </varlistentry>
 6673
 6674            <varlistentry>
 6675              <term><command>dnssec-validation</command></term>
 6676              <listitem>
 6677                <para>
 6678                  Enable DNSSEC validation in <command>named</command>.
 6679		  Note <command>dnssec-enable</command> also needs to be
 6680		  set to <userinput>yes</userinput> to be effective.
 6681                  If set to <userinput>no</userinput>, DNSSEC validation
 6682                  is disabled.  If set to <userinput>auto</userinput>,
 6683                  DNSSEC validation is enabled, and a default
 6684                  trust-anchor for the DNS root zone is used.  If set to
 6685                  <userinput>yes</userinput>, DNSSEC validation is enabled,
 6686                  but a trust anchor must be manually configured using
 6687                  a <command>trusted-keys</command> or
 6688                  <command>managed-keys</command> statement.  The default
 6689                  is <userinput>yes</userinput>.
 6690                </para>
 6691              </listitem>
 6692            </varlistentry>
 6693
 6694            <varlistentry>
 6695              <term><command>dnssec-accept-expired</command></term>
 6696              <listitem>
 6697                <para>
 6698		  Accept expired signatures when verifying DNSSEC signatures.
 6699                  The default is <userinput>no</userinput>.
 6700		  Setting this option to <userinput>yes</userinput>
 6701		  leaves <command>named</command> vulnerable to
 6702		  replay attacks.
 6703                </para>
 6704              </listitem>
 6705            </varlistentry>
 6706
 6707            <varlistentry>
 6708              <term><command>querylog</command></term>
 6709              <listitem>
 6710                <para>
 6711                  Specify whether query logging should be started when <command>named</command>
 6712                  starts.
 6713                  If <command>querylog</command> is not specified,
 6714                  then the query logging
 6715                  is determined by the presence of the logging category <command>queries</command>.
 6716                </para>
 6717              </listitem>
 6718            </varlistentry>
 6719
 6720            <varlistentry>
 6721              <term><command>check-names</command></term>
 6722              <listitem>
 6723                <para>
 6724                  This option is used to restrict the character set and syntax
 6725                  of
 6726                  certain domain names in master files and/or DNS responses
 6727                  received
 6728                  from the network.  The default varies according to usage
 6729                  area.  For
 6730                  <command>master</command> zones the default is <command>fail</command>.
 6731                  For <command>slave</command> zones the default
 6732                  is <command>warn</command>.
 6733                  For answers received from the network (<command>response</command>)
 6734                  the default is <command>ignore</command>.
 6735                </para>
 6736                <para>
 6737                  The rules for legal hostnames and mail domains are derived
 6738                  from RFC 952 and RFC 821 as modified by RFC 1123.
 6739                </para>
 6740                <para><command>check-names</command>
 6741		  applies to the owner names of A, AAAA and MX records.
 6742		  It also applies to the domain names in the RDATA of NS, SOA,
 6743		  MX, and SRV records.
 6744		  It also applies to the RDATA of PTR records where the owner
 6745		  name indicated that it is a reverse lookup of a hostname
 6746		  (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT).
 6747                </para>
 6748              </listitem>
 6749            </varlistentry>
 6750
 6751	    <varlistentry>
 6752	      <term><command>check-dup-records</command></term>
 6753	      <listitem>
 6754		<para>
 6755		  Check master zones for records that are treated as different
 6756		  by DNSSEC but are semantically equal in plain DNS.  The
 6757		  default is to <command>warn</command>.  Other possible
 6758		  values are <command>fail</command> and
 6759		  <command>ignore</command>.
 6760		</para>
 6761	      </listitem>
 6762	    </varlistentry>
 6763
 6764	    <varlistentry>
 6765	      <term><command>check-mx</command></term>
 6766	      <listitem>
 6767		<para>
 6768		  Check whether the MX record appears to refer to a IP address.
 6769		  The default is to <command>warn</command>.  Other possible
 6770		  values are <command>fail</command> and
 6771		  <command>ignore</command>.
 6772		</para>
 6773	      </listitem>
 6774	    </varlistentry>
 6775
 6776            <varlistentry>
 6777              <term><command>check-wildcard</command></term>
 6778              <listitem>
 6779                <para>
 6780                  This option is used to check for non-terminal wildcards.
 6781                  The use of non-terminal wildcards is almost always as a
 6782                  result of a failure
 6783                  to understand the wildcard matching algorithm (RFC 1034).
 6784                  This option
 6785                  affects master zones.  The default (<command>yes</command>) is to check
 6786                  for non-terminal wildcards and issue a warning.
 6787                </para>
 6788              </listitem>
 6789            </varlistentry>
 6790
 6791	    <varlistentry>
 6792	      <term><command>check-integrity</command></term>
 6793	      <listitem>
 6794		<para>
 6795		  Perform post load zone integrity checks on master
 6796		  zones.  This checks that MX and SRV records refer
 6797		  to address (A or AAAA) records and that glue
 6798		  address records exist for delegated zones.  For
 6799		  MX and SRV records only in-zone hostnames are
 6800		  checked (for out-of-zone hostnames use
 6801		  <command>named-checkzone</command>).
 6802		  For NS records only names below top of zone are
 6803		  checked (for out-of-zone names and glue consistency
 6804		  checks use <command>named-checkzone</command>).
 6805	          The default is <command>yes</command>.
 6806		</para>
 6807	      </listitem>
 6808	    </varlistentry>
 6809
 6810	    <varlistentry>
 6811	      <term><command>check-mx-cname</command></term>
 6812	      <listitem>
 6813		<para>
 6814		  If <command>check-integrity</command> is set then
 6815		  fail, warn or ignore MX records that refer
 6816		  to CNAMES.  The default is to <command>warn</command>.
 6817		</para>
 6818	      </listitem>
 6819	    </varlistentry>
 6820
 6821	    <varlistentry>
 6822	      <term><command>check-srv-cname</command></term>
 6823	      <listitem>
 6824		<para>
 6825		  If <command>check-integrity</command> is set then
 6826		  fail, warn or ignore SRV records that refer
 6827		  to CNAMES.  The default is to <command>warn</command>.
 6828		</para>
 6829	      </listitem>
 6830	    </varlistentry>
 6831
 6832	    <varlistentry>
 6833	      <term><command>check-sibling</command></term>
 6834	      <listitem>
 6835		<para>
 6836		  When performing integrity checks, also check that
 6837		  sibling glue exists.  The default is <command>yes</command>.
 6838		</para>
 6839	      </listitem>
 6840	    </varlistentry>
 6841
 6842	    <varlistentry>
 6843	      <term><command>zero-no-soa-ttl</command></term>
 6844	      <listitem>
 6845	        <para>
 6846		  When returning authoritative negative responses to
 6847		  SOA queries set the TTL of the SOA record returned in
 6848		  the authority section to zero.
 6849		  The default is <command>yes</command>.
 6850	        </para>
 6851	      </listitem>
 6852	    </varlistentry>
 6853
 6854	    <varlistentry>
 6855	      <term><command>zero-no-soa-ttl-cache</command></term>
 6856	      <listitem>
 6857	        <para>
 6858		  When caching a negative response to a SOA query
 6859		  set the TTL to zero.
 6860		  The default is <command>no</command>.
 6861	        </para>
 6862	      </listitem>
 6863	    </varlistentry>
 6864
 6865	    <varlistentry>
 6866	      <term><command>update-check-ksk</command></term>
 6867	      <listitem>
 6868	        <para>
 6869                  When set to the default value of <literal>yes</literal>,
 6870                  check the KSK bit in each key to determine how the key
 6871                  should be used when generating RRSIGs for a secure zone.
 6872		</para>
 6873		<para>
 6874                  Ordinarily, zone-signing keys (that is, keys without the
 6875                  KSK bit set) are used to sign the entire zone, while
 6876                  key-signing keys (keys with the KSK bit set) are only
 6877                  used to sign the DNSKEY RRset at the zone apex.
 6878                  However, if this option is set to <literal>no</literal>,
 6879                  then the KSK bit is ignored; KSKs are treated as if they
 6880                  were ZSKs and are used to sign the entire zone.  This is
 6881                  similar to the <command>dnssec-signzone -z</command>
 6882                  command line option.
 6883		</para>
 6884		<para>
 6885                  When this option is set to <literal>yes</literal>, there
 6886                  must be at least two active keys for every algorithm
 6887                  represented in the DNSKEY RRset: at least one KSK and one
 6888                  ZSK per algorithm.  If there is any algorithm for which
 6889                  this requirement is not met, this option will be ignored
 6890                  for that algorithm.
 6891		</para>
 6892	      </listitem>
 6893	    </varlistentry>
 6894
 6895	    <varlistentry>
 6896	      <term><command>dnssec-dnskey-kskonly</command></term>
 6897	      <listitem>
 6898	        <para>
 6899                  When this option and <command>update-check-ksk</command>
 6900                  are both set to <literal>yes</literal>, only key-signing
 6901                  keys (that is, keys with the KSK bit set) will be used
 6902                  to sign the DNSKEY RRset at the zone apex.  Zone-signing
 6903                  keys (keys without the KSK bit set) will be used to sign
 6904                  the remainder of the zone, but not the DNSKEY RRset.
 6905                  This is similar to the
 6906                  <command>dnssec-signzone -x</command> command line option.
 6907		</para>
 6908		<para>
 6909		  The default is <command>no</command>.  If
 6910                  <command>update-check-ksk</command> is set to
 6911                  <literal>no</literal>, this option is ignored.
 6912		</para>
 6913	      </listitem>
 6914	    </varlistentry>
 6915
 6916	    <varlistentry>
 6917	      <term><command>try-tcp-refresh</command></term>
 6918	      <listitem>
 6919	        <para>
 6920		  Try to refresh the zone using TCP if UDP queries fail.
 6921		  For BIND 8 compatibility, the default is
 6922		  <command>yes</command>.
 6923		</para>
 6924	      </listitem>
 6925	    </varlistentry>
 6926
 6927	    <varlistentry>
 6928	      <term><command>dnssec-secure-to-insecure</command></term>
 6929	      <listitem>
 6930	        <para>
 6931		  Allow a dynamic zone to transition from secure to
 6932                  insecure (i.e., signed to unsigned) by deleting all
 6933                  of the DNSKEY records.  The default is <command>no</command>.
 6934                  If set to <command>yes</command>, and if the DNSKEY RRset
 6935                  at the zone apex is deleted, all RRSIG and NSEC records
 6936                  will be removed from the zone as well.
 6937		</para>
 6938	        <para>
 6939                  If the zone uses NSEC3, then it is also necessary to
 6940                  delete the NSEC3PARAM RRset from the zone apex; this will
 6941                  cause the removal of all corresponding NSEC3 records.
 6942                  (It is expected that this requirement will be eliminated
 6943                  in a future release.)
 6944		</para>
 6945	        <para>
 6946                  Note that if a zone has been configured with
 6947                  <command>auto-dnssec maintain</command> and the
 6948                  private keys remain accessible in the key repository,
 6949                  then the zone will be automatically signed again the
 6950                  next time <command>named</command> is started.
 6951		</para>
 6952	      </listitem>
 6953	    </varlistentry>
 6954
 6955          </variablelist>
 6956
 6957        </sect3>
 6958
 6959        <sect3>
 6960          <title>Forwarding</title>
 6961          <para>
 6962            The forwarding facility can be used to create a large site-wide
 6963            cache on a few servers, reducing traffic over links to external
 6964            name servers. It can also be used to allow queries by servers that
 6965            do not have direct access to the Internet, but wish to look up
 6966            exterior
 6967            names anyway. Forwarding occurs only on those queries for which
 6968            the server is not authoritative and does not have the answer in
 6969            its cache.
 6970          </para>
 6971
 6972          <variablelist>
 6973            <varlistentry>
 6974              <term><command>forward</command></term>
 6975              <listitem>
 6976                <para>
 6977                  This option is only meaningful if the
 6978                  forwarders list is not empty. A value of <varname>first</varname>,
 6979                  the default, causes the server to query the forwarders
 6980                  first &mdash; and
 6981                  if that doesn't answer the question, the server will then
 6982                  look for
 6983                  the answer itself. If <varname>only</varname> is
 6984                  specified, the
 6985                  server will only query the forwarders.
 6986                </para>
 6987              </listitem>
 6988            </varlistentry>
 6989
 6990            <varlistentry>
 6991              <term><command>forwarders</command></term>
 6992              <listitem>
 6993                <para>
 6994                  Specifies the IP addresses to be used
 6995                  for forwarding. The default is the empty list (no
 6996                  forwarding).
 6997                </para>
 6998              </listitem>
 6999            </varlistentry>
 7000
 7001          </variablelist>
 7002
 7003          <para>
 7004            Forwarding can also be configured on a per-domain basis, allowing
 7005            for the global forwarding options to be overridden in a variety
 7006            of ways. You can set particular domains to use different
 7007            forwarders,
 7008            or have a different <command>forward only/first</command> behavior,
 7009            or not forward at all, see <xref linkend="zone_statement_grammar"/>.
 7010          </para>
 7011        </sect3>
 7012
 7013        <sect3>
 7014          <title>Dual-stack Servers</title>
 7015          <para>
 7016            Dual-stack servers are used as servers of last resort to work
 7017            around
 7018            problems in reachability due the lack of support for either IPv4
 7019            or IPv6
 7020            on the host machine.
 7021          </para>
 7022
 7023          <variablelist>
 7024            <varlistentry>
 7025              <term><command>dual-stack-servers</command></term>
 7026              <listitem>
 7027                <para>
 7028                  Specifies host names or addresses of machines with access to
 7029                  both IPv4 and IPv6 transports. If a hostname is used, the
 7030                  server must be able
 7031                  to resolve the name using only the transport it has.  If the
 7032                  machine is dual
 7033                  stacked, then the <command>dual-stack-servers</command> have no effect unless
 7034                  access to a transport has been disabled on the command line
 7035                  (e.g. <command>named -4</command>).
 7036                </para>
 7037              </listitem>
 7038            </varlistentry>
 7039          </variablelist>
 7040        </sect3>
 7041
 7042        <sect3 id="access_control">
 7043          <title>Access Control</title>
 7044
 7045          <para>
 7046            Access to the server can be restricted based on the IP address
 7047            of the requesting system. See <xref linkend="address_match_lists"/> for
 7048            details on how to specify IP address lists.
 7049          </para>
 7050
 7051          <variablelist>
 7052
 7053            <varlistentry>
 7054              <term><command>allow-notify</command></term>
 7055              <listitem>
 7056                <para>
 7057                  Specifies which hosts are allowed to
 7058                  notify this server, a slave, of zone changes in addition
 7059                  to the zone masters.
 7060                  <command>allow-notify</command> may also be
 7061                  specified in the
 7062                  <command>zone</command> statement, in which case
 7063                  it overrides the
 7064                  <command>options allow-notify</command>
 7065                  statement.  It is only meaningful
 7066                  for a slave zone.  If not specified, the default is to
 7067                  process notify messages
 7068                  only from a zone's master.
 7069                </para>
 7070              </listitem>
 7071            </varlistentry>
 7072
 7073	    <varlistentry>
 7074	      <term><command>allow-query</command></term>
 7075	      <listitem>
 7076		<para>
 7077		  Specifies which hosts are allowed to ask ordinary
 7078		  DNS questions. <command>allow-query</command> may
 7079		  also be specified in the <command>zone</command>
 7080		  statement, in which case it overrides the
 7081		  <command>options allow-query</command> statement.
 7082		  If not specified, the default is to allow queries
 7083		  from all hosts.
 7084		</para>
 7085		<note>
 7086		  <para>
 7087		    <command>allow-query-cache</command> is now
 7088		    used to specify access to the cache.
 7089		  </para>
 7090		</note>
 7091	      </listitem>
 7092	    </varlistentry>
 7093
 7094	    <varlistentry>
 7095	      <term><command>allow-query-on</command></term>
 7096	      <listitem>
 7097		<para>
 7098		  Specifies which local addresses can accept ordinary
 7099		  DNS questions. This makes it possible, for instance,
 7100		  to allow queries on internal-facing interfaces but
 7101		  disallow them on external-facing ones, without
 7102		  necessarily knowing the internal network's addresses.
 7103		</para>
 7104		<para>
 7105		  <command>allow-query-on</command> may
 7106		  also be specified in the <command>zone</command>
 7107		  statement, in which case it overrides the
 7108		  <command>options allow-query-on</command> statement.
 7109		</para>
 7110		<para>
 7111		  If not specified, the default is to allow queries
 7112		  on all addresses.
 7113		</para>
 7114		<note>
 7115		  <para>
 7116		    <command>allow-query-cache</command> is
 7117		    used to specify access to the cache.
 7118		  </para>
 7119		</note>
 7120	      </listitem>
 7121	    </varlistentry>
 7122
 7123	    <varlistentry>
 7124	      <term><command>allow-query-cache</command></term>
 7125	      <listitem>
 7126		<para>
 7127		  Specifies which hosts are allowed to get answers
 7128		  from the cache.  If <command>allow-query-cache</command>
 7129		  is not set then <command>allow-recursion</command>
 7130		  is used if set, otherwise <command>allow-query</command>
 7131		  is used if set unless <command>recursion no;</command> is
 7132		  set in which case <command>none;</command> is used,
 7133		  otherwise the default (<command>localnets;</command>
 7134		  <command>localhost;</command>) is used.
 7135		</para>
 7136	      </listitem>
 7137	    </varlistentry>
 7138
 7139	    <varlistentry>
 7140	      <term><command>allow-query-cache-on</command></term>
 7141	      <listitem>
 7142		<para>
 7143		  Specifies which local addresses can give answers
 7144		  from the cache.  If not specified, the default is
 7145		  to allow cache queries on any address,
 7146		  <command>localnets</command> and
 7147		  <command>localhost</command>.
 7148		</para>
 7149	      </listitem>
 7150	    </varlistentry>
 7151
 7152            <varlistentry>
 7153              <term><command>allow-recursion</command></term>
 7154              <listitem>
 7155		<para>
 7156		  Specifies which hosts are allowed to make recursive
 7157		  queries through this server. If
 7158		  <command>allow-recursion</command> is not set
 7159		  then <command>allow-query-cache</command> is
 7160		  used if set, otherwise <command>allow-query</command>
 7161		  is used if set, otherwise the default
 7162		  (<command>localnets;</command>
 7163		  <command>localhost;</command>) is used.
 7164		</para>
 7165              </listitem>
 7166            </varlistentry>
 7167
 7168            <varlistentry>
 7169              <term><command>allow-recursion-on</command></term>
 7170              <listitem>
 7171                <para>
 7172		  Specifies which local addresses can accept recursive
 7173		  queries.  If not specified, the default is to allow
 7174		  recursive queries on all addresses.
 7175                </para>
 7176              </listitem>
 7177            </varlistentry>
 7178
 7179            <varlistentry>
 7180              <term><command>allow-update</command></term>
 7181              <listitem>
 7182                <para>
 7183                  Specifies which hosts are allowed to
 7184                  submit Dynamic DNS updates for master zones. The default is
 7185                  to deny
 7186                  updates from all hosts.  Note that allowing updates based
 7187                  on the requestor's IP address is insecure; see
 7188                  <xref linkend="dynamic_update_security"/> for details.
 7189                </para>
 7190              </listitem>
 7191            </varlistentry>
 7192
 7193            <varlistentry>
 7194              <term><command>allow-update-forwarding</command></term>
 7195              <listitem>
 7196                <para>
 7197                  Specifies which hosts are allowed to
 7198                  submit Dynamic DNS updates to slave zones to be forwarded to
 7199                  the
 7200                  master.  The default is <userinput>{ none; }</userinput>,
 7201                  which
 7202                  means that no update forwarding will be performed.  To
 7203                  enable
 7204                  update forwarding, specify
 7205                  <userinput>allow-update-forwarding { any; };</userinput>.
 7206                  Specifying values other than <userinput>{ none; }</userinput> or
 7207                  <userinput>{ any; }</userinput> is usually
 7208                  counterproductive, since
 7209                  the responsibility for update access control should rest
 7210                  with the
 7211                  master server, not the slaves.
 7212                </para>
 7213                <para>
 7214                  Note that enabling the update forwarding feature on a slave
 7215                  server
 7216                  may expose master servers relying on insecure IP address
 7217                  based
 7218                  access control to attacks; see <xref linkend="dynamic_update_security"/>
 7219                  for more details.
 7220                </para>
 7221              </listitem>
 7222            </varlistentry>
 7223
 7224            <varlistentry>
 7225              <term><command>allow-v6-synthesis</command></term>
 7226              <listitem>
 7227                <para>
 7228                  This option was introduced for the smooth transition from
 7229                  AAAA
 7230                  to A6 and from "nibble labels" to binary labels.
 7231                  However, since both A6 and binary labels were then
 7232                  deprecated,
 7233                  this option was also deprecated.
 7234                  It is now ignored with some warning messages.
 7235                </para>
 7236              </listitem>
 7237            </varlistentry>
 7238
 7239            <varlistentry>
 7240              <term><command>allow-transfer</command></term>
 7241              <listitem>
 7242                <para>
 7243                  Specifies which hosts are allowed to
 7244                  receive zone transfers from the server. <command>allow-transfer</command> may
 7245                  also be specified in the <command>zone</command>
 7246                  statement, in which
 7247                  case it overrides the <command>options allow-transfer</command> statement.
 7248                  If not specified, the default is to allow transfers to all
 7249                  hosts.
 7250                </para>
 7251              </listitem>
 7252            </varlistentry>
 7253
 7254            <varlistentry>
 7255              <term><command>blackhole</command></term>
 7256              <listitem>
 7257                <para>
 7258                  Specifies a list of addresses that the
 7259                  server will not accept queries from or use to resolve a
 7260                  query. Queries
 7261                  from these addresses will not be responded to. The default
 7262                  is <userinput>none</userinput>.
 7263                </para>
 7264              </listitem>
 7265            </varlistentry>
 7266
 7267            <varlistentry>
 7268              <term><command>filter-aaaa</command></term>
 7269              <listitem>
 7270                <para>
 7271                  Specifies a list of addresses to which
 7272		  <command>filter-aaaa-on-v4</command>
 7273                  is applies.  The default is <userinput>any</userinput>.
 7274                </para>
 7275              </listitem>
 7276            </varlistentry>
 7277
 7278            <varlistentry>
 7279              <term><command>resolver-query-timeout</command></term>
 7280              <listitem>
 7281                <para>
 7282		  The amount of time the resolver will spend attempting
 7283		  to resolve a recursive query before failing.  The
 7284		  default is <literal>10</literal> and the maximum is
 7285		  <literal>30</literal>.  Setting it to <literal>0</literal>
 7286		  will result in the default being used.
 7287                </para>
 7288              </listitem>
 7289            </varlistentry>
 7290          </variablelist>
 7291
 7292        </sect3>
 7293
 7294        <sect3>
 7295          <title>Interfaces</title>
 7296          <para>
 7297            The interfaces and ports that the server will answer queries
 7298            from may be specified using the <command>listen-on</command> option. <command>listen-on</command> takes
 7299            an optional port and an <varname>address_match_list</varname>.
 7300            The server will listen on all interfaces allowed by the address
 7301            match list. If a port is not specified, port 53 will be used.
 7302          </para>
 7303          <para>
 7304            Multiple <command>listen-on</command> statements are
 7305            allowed.
 7306            For example,
 7307          </para>
 7308
 7309<programlisting>listen-on { 5.6.7.8; };
 7310listen-on port 1234 { !1.2.3.4; 1.2/16; };
 7311</programlisting>
 7312
 7313          <para>
 7314            will enable the name server on port 53 for the IP address
 7315            5.6.7.8, and on port 1234 of an address on the machine in net
 7316            1.2 that is not 1.2.3.4.
 7317          </para>
 7318
 7319          <para>
 7320            If no <command>listen-on</command> is specified, the
 7321            server will listen on port 53 on all IPv4 interfaces.
 7322          </para>
 7323
 7324          <para>
 7325            The <command>listen-on-v6</command> option is used to
 7326            specify the interfaces and the ports on which the server will
 7327            listen
 7328            for incoming queries sent using IPv6.
 7329          </para>
 7330
 7331          <para>
 7332            When <programlisting>{ any; }</programlisting> is
 7333            specified
 7334            as the <varname>address_match_list</varname> for the
 7335            <command>listen-on-v6</command> option,
 7336            the server does not bind a separate socket to each IPv6 interface
 7337            address as it does for IPv4 if the operating system has enough API
 7338            support for IPv6 (specifically if it conforms to RFC 3493 and RFC
 7339            3542).
 7340            Instead, it listens on the IPv6 wildcard address.
 7341            If the system only has incomplete API support for IPv6, however,
 7342            the behavior is the same as that for IPv4.
 7343          </para>
 7344
 7345          <para>
 7346            A list of particular IPv6 addresses can also be specified, in
 7347            which case
 7348            the server listens on a separate socket for each specified
 7349            address,
 7350            regardless of whether the desired API is supported by the system.
 7351          </para>
 7352
 7353          <para>
 7354            Multiple <command>listen-on-v6</command> options can
 7355            be used.
 7356            For example,
 7357          </para>
 7358
 7359<programlisting>listen-on-v6 { any; };
 7360listen-on-v6 port 1234 { !2001:db8::/32; any; };
 7361</programlisting>
 7362
 7363          <para>
 7364            will enable the name server on port 53 for any IPv6 addresses
 7365            (with a single wildcard socket),
 7366            and on port 1234 of IPv6 addresses that is not in the prefix
 7367            2001:db8::/32 (with separate sockets for each matched address.)
 7368          </para>
 7369
 7370          <para>
 7371            To make the server not listen on any IPv6 address, use
 7372          </para>
 7373
 7374<programlisting>listen-on-v6 { none; };
 7375</programlisting>
 7376
 7377          <para>
 7378            If no <command>listen-on-v6</command> option is
 7379            specified, the server will not listen on any IPv6 address
 7380	    unless <command>-6</command> is specified when <command>named</command> is
 7381	    invoked.  If <command>-6</command> is specified then
 7382	    <command>named</command> will listen on port 53 on all IPv6 interfaces by default.
 7383          </para>
 7384        </sect3>
 7385
 7386        <sect3 id="query_address">
 7387          <title>Query Address</title>
 7388          <para>
 7389            If the server doesn't know the answer to a question, it will
 7390            query other name servers. <command>query-source</command> specifies
 7391            the address and port used for such queries. For queries sent over
 7392            IPv6, there is a separate <command>query-source-v6</command> option.
 7393            If <command>address</command> is <command>*</command> (asterisk) or is omitted,
 7394            a wildcard IP address (<command>INADDR_ANY</command>)
 7395            will be used.
 7396	  </para>
 7397
 7398	  <para>
 7399            If <command>port</command> is <command>*</command> or is omitted,
 7400	    a random port number from a pre-configured
 7401	    range is picked up and will be used for each query.
 7402	    The port range(s) is that specified in
 7403	    the <command>use-v4-udp-ports</command> (for IPv4)
 7404            and <command>use-v6-udp-ports</command> (for IPv6)
 7405	    options, excluding the ranges specified in
 7406	    the <command>avoid-v4-udp-ports</command>
 7407            and <command>avoid-v6-udp-ports</command> options, respectively.
 7408	  </para>
 7409
 7410          <para>
 7411	    The defaults of the <command>query-source</command> and
 7412	    <command>query-source-v6</command> options
 7413	    are:
 7414          </para>
 7415
 7416<programlisting>query-source address * port *;
 7417query-source-v6 address * port *;
 7418</programlisting>
 7419
 7420          <para>
 7421	    If <command>use-v4-udp-ports</command> or
 7422            <command>use-v6-udp-ports</command> is unspecified,
 7423	    <command>named</command> will check if the operating
 7424	    system provides a programming interface to retrieve the
 7425	    system's default range for ephemeral ports.
 7426	    If such an interface is available,
 7427	    <command>named</command> will use the corresponding system
 7428	    default range; otherwise, it will use its own defaults:
 7429         </para>
 7430
 7431<programlisting>use-v4-udp-ports { range 1024 65535; };
 7432use-v6-udp-ports { range 1024 65535; };
 7433</programlisting>
 7434
 7435          <para>
 7436	    Note: make sure the ranges be sufficiently large for
 7437	    security.  A desirable size depends on various parameters,
 7438	    but we generally recommend it contain at least 16384 ports
 7439	    (14 bits of entropy).
 7440	    Note also that the system's default range when used may be
 7441	    too small for this purpose, and that the range may even be
 7442	    changed while <command>named</command> is running; the new
 7443	    range will automatically be applied when <command>named</command>
 7444	    is reloaded.
 7445	    It is encouraged to
 7446	    configure <command>use-v4-udp-ports</command> and
 7447            <command>use-v6-udp-ports</command> explicitly so that the
 7448            ranges are sufficiently large and are reasonably
 7449            independent from the ranges used by other applications.
 7450          </para>
 7451
 7452	  <para>
 7453	    Note: the operational configuration
 7454	    where <command>named</command> runs may prohibit the use
 7455	    of some ports.  For example, UNIX systems will not allow
 7456	    <command>named</command> running without a root privilege
 7457	    to use ports less than 1024.
 7458	    If such ports are included in the specified (or detected)
 7459	    set of query ports, the corresponding query attempts will
 7460	    fail, resulting in resolution failures or delay.
 7461	    It is therefore important to configure the set of ports
 7462	    that can be safely used in the expected operational environment.
 7463	  </para>
 7464
 7465          <para>
 7466	    The defaults of the <command>avoid-v4-udp-ports</command> and
 7467	    <command>avoid-v6-udp-ports</command> options
 7468	    are:
 7469          </para>
 7470
 7471<programlisting>avoid-v4-udp-ports {};
 7472avoid-v6-udp-ports {};
 7473</programlisting>
 7474
 7475	  <para>
 7476	    Note: BIND 9.5.0 introduced
 7477	    the <command>use-queryport-pool</command> 
 7478	    option to support a pool of such random ports, but this
 7479	    option is now obsolete because reusing the same ports in
 7480	    the pool may not be sufficiently secure.
 7481	    For the same reason, it is generally strongly discouraged to
 7482            specify a particular port for the
 7483	    <command>query-source</command> or
 7484	    <command>query-source-v6</command> options;
 7485	    it implicitly disables the use of randomized port numbers.
 7486          </para>
 7487
 7488          <variablelist>
 7489            <varlistentry>
 7490              <term><command>use-queryport-pool</command></term>
 7491              <listitem>
 7492                <para>
 7493		  This option is obsolete.
 7494		</para>
 7495	      </listitem>
 7496	    </varlistentry>
 7497
 7498            <varlistentry>
 7499              <term><command>queryport-pool-ports</command></term>
 7500              <listitem>
 7501                <para>
 7502		  This option is obsolete.
 7503		</para>
 7504	      </listitem>
 7505	    </varlistentry>
 7506
 7507            <varlistentry>
 7508              <term><command>queryport-pool-updateinterval</command></term>
 7509              <listitem>
 7510                <para>
 7511		  This option is obsolete.
 7512		</para>
 7513	      </listitem>
 7514	    </varlistentry>
 7515	    
 7516          </variablelist>
 7517          <note>
 7518            <para>
 7519              The address specified in the <command>query-source</command> option
 7520              is used for both UDP and TCP queries, but the port applies only
 7521              to UDP queries.  TCP queries always use a random
 7522              unprivileged port.
 7523            </para>
 7524          </note>
 7525	  <note>
 7526	    <para>
 7527	      Solaris 2.5.1 and earlier does not support setting the source
 7528	      address for TCP sockets.
 7529	    </para>
 7530	  </note>
 7531          <note>
 7532            <para>
 7533              See also <command>transfer-source</command> and
 7534              <command>notify-source</command>.
 7535            </para>
 7536          </note>
 7537        </sect3>
 7538
 7539        <sect3 id="zone_transfers">
 7540          <title>Zone Transfers</title>
 7541          <para>
 7542            <acronym>BIND</acronym> has mechanisms in place to
 7543            facilitate zone transfers
 7544            and set limits on the amount of load that transfers place on the
 7545            system. The following options apply to zone transfers.
 7546          </para>
 7547
 7548          <variablelist>
 7549
 7550            <varlistentry>
 7551              <term><command>also-notify</command></term>
 7552              <listitem>
 7553                <para>
 7554                  Defines a global list of IP addresses of name servers
 7555                  that are also sent NOTIFY messages whenever a fresh copy of
 7556                  the
 7557                  zone is loaded, in addition to the servers listed in the
 7558                  zone's NS records.
 7559                  This helps to ensure that copies of the zones will
 7560                  quickly converge on stealth servers.
 7561                  Optionally, a port may be specified with each
 7562                  <command>also-notify</command> address to send
 7563                  the notify messages to a port other than the
 7564                  default of 53.
 7565                  If an <command>also-notify</command> list
 7566                  is given in a <command>zone</command> statement,
 7567                  it will override
 7568                  the <command>options also-notify</command>
 7569                  statement. When a <command>zone notify</command>
 7570                  statement
 7571                  is set to <command>no</command>, the IP
 7572                  addresses in the global <command>also-notify</command> list will
 7573                  not be sent NOTIFY messages for that zone. The default is
 7574                  the empty
 7575                  list (no global notification list).
 7576                </para>
 7577              </listitem>
 7578            </varlistentry>
 7579
 7580            <varlistentry>
 7581              <term><command>max-transfer-time-in</command></term>
 7582              <listitem>
 7583                <para>
 7584                  Inbound zone transfers running longer than
 7585                  this many minutes will be terminated. The default is 120
 7586                  minutes
 7587                  (2 hours).  The maximum value is 28 days (40320 minutes).
 7588                </para>
 7589              </listitem>
 7590            </varlistentry>
 7591
 7592            <varlistentry>
 7593              <term><command>max-transfer-idle-in</command></term>
 7594              <listitem>
 7595                <para>
 7596                  Inbound zone transfers making no progress
 7597                  in this many minutes will be terminated. The default is 60
 7598                  minutes
 7599                  (1 hour).  The maximum value is 28 days (40320 minutes).
 7600                </para>
 7601              </listitem>
 7602            </varlistentry>
 7603
 7604            <varlistentry>
 7605              <term><command>max-transfer-time-out</command></term>
 7606              <listitem>
 7607                <para>
 7608                  Outbound zone transfers running longer than
 7609                  this many minutes will be terminated. The default is 120
 7610                  minutes
 7611                  (2 hours).  The maximum value is 28 days (40320 minutes).
 7612                </para>
 7613              </listitem>
 7614            </varlistentry>
 7615
 7616            <varlistentry>
 7617              <term><command>max-transfer-idle-out</command></term>
 7618              <listitem>
 7619                <para>
 7620                  Outbound zone transfers making no progress
 7621                  in this many minutes will be terminated.  The default is 60
 7622                  minutes (1
 7623                  hour).  The maximum value is 28 days (40320 minutes).
 7624                </para>
 7625              </listitem>
 7626            </varlistentry>
 7627
 7628            <varlistentry>
 7629              <term><command>serial-query-rate</command></term>
 7630	      <listitem>
 7631		<para>
 7632		  Slave servers will periodically query master
 7633		  servers to find out if zone serial numbers have
 7634		  changed. Each such query uses a minute amount of
 7635		  the slave server's network bandwidth.  To limit
 7636		  the amount of bandwidth used, BIND 9 limits the
 7637		  rate at which queries are sent.  The value of the
 7638		  <command>serial-query-rate</command> option, an
 7639		  integer, is the maximum number of queries sent
 7640		  per second.  The default is 20.
 7641		</para>
 7642		<para>
 7643		  In addition to controlling the rate SOA refresh
 7644		  queries are issued at
 7645		  <command>serial-query-rate</command> also controls
 7646		  the rate at which NOTIFY messages are sent from
 7647		  both master and slave zones.
 7648		</para>
 7649	      </listitem>
 7650	    </varlistentry>
 7651
 7652            <varlistentry>
 7653              <term><command>serial-queries</command></term>
 7654              <listitem>
 7655                <para>
 7656                  In BIND 8, the <command>serial-queries</command>
 7657                  option
 7658                  set the maximum number of concurrent serial number queries
 7659                  allowed to be outstanding at any given time.
 7660                  BIND 9 does not limit the number of outstanding
 7661                  serial queries and ignores the <command>serial-queries</command> option.
 7662                  Instead, it limits the rate at which the queries are sent
 7663                  as defined using the <command>serial-query-rate</command> option.
 7664                </para>
 7665              </listitem>
 7666            </varlistentry>
 7667
 7668            <varlistentry>
 7669              <term><command>transfer-format</command></term>
 7670              <listitem>
 7671
 7672                <para>
 7673                  Zone transfers can be sent using two different formats,
 7674                  <command>one-answer</command> and
 7675		  <command>many-answers</command>.
 7676                  The <command>transfer-format</command> option is used
 7677                  on the master server to determine which format it sends.
 7678                  <command>one-answer</command> uses one DNS message per
 7679                  resource record transferred.
 7680                  <command>many-answers</command> packs as many resource
 7681		  records as possible into a message.
 7682		  <command>many-answers</command> is more efficient, but is
 7683		  only supported by relatively new slave servers,
 7684                  such as <acronym>BIND</acronym> 9, <acronym>BIND</acronym>
 7685		  8.x and <acronym>BIND</acronym> 4.9.5 onwards.
 7686	          The <command>many-answers</command> format is also supported by
 7687		  recent Microsoft Windows nameservers.
 7688		  The default is <command>many-answers</command>.
 7689		  <command>transfer-format</command> may be overridden on a
 7690		  per-server basis by using the <command>server</command>
 7691		  statement.
 7692                </para>
 7693
 7694              </listitem>
 7695            </varlistentry>
 7696
 7697            <varlistentry>
 7698              <term><command>transfers-in</command></term>
 7699              <listitem>
 7700                <para>
 7701                  The maximum number of inbound zone transfers
 7702                  that can be running concurrently. The default value is <literal>10</literal>.
 7703                  Increasing <command>transfers-in</command> may
 7704                  speed up the convergence
 7705                  of slave zones, but it also may increase the load on the
 7706                  local system.
 7707                </para>
 7708              </listitem>
 7709            </varlistentry>
 7710
 7711            <varlistentry>
 7712              <term><command>transfers-out</command></term>
 7713              <listitem>
 7714                <para>
 7715                  The maximum number of outbound zone transfers
 7716                  that can be running concurrently. Zone transfer requests in
 7717                  excess
 7718                  of the limit will be refused. The default value is <literal>10</literal>.
 7719                </para>
 7720              </listitem>
 7721            </varlistentry>
 7722
 7723            <varlistentry>
 7724              <term><command>transfers-per-ns</command></term>
 7725              <listitem>
 7726                <para>
 7727                  The maximum number of inbound zone transfers
 7728                  that can be concurrently transferring from a given remote
 7729                  name server.
 7730                  The default value is <literal>2</literal>.
 7731                  Increasing <command>transfers-per-ns</command>
 7732                  may
 7733                  speed up the convergence of slave zones, but it also may
 7734                  increase
 7735                  the load on the remote name server. <command>transfers-per-ns</command> may
 7736                  be overridden on a per-server basis by using the <command>transfers</command> phrase
 7737                  of the <command>server</command> statement.
 7738                </para>
 7739              </listitem>
 7740            </varlistentry>
 7741
 7742            <varlistentry>
 7743              <term><command>transfer-source</command></term>
 7744              <listitem>
 7745                <para><command>transfer-source</command>
 7746		  determines which local address will be bound to IPv4
 7747                  TCP connections used to fetch zones transferred
 7748                  inbound by the server.  It also determines the
 7749                  source IPv4 address, and optionally the UDP port,
 7750                  used for the refresh queries and forwarded dynamic
 7751                  updates.  If not set, it defaults to a system
 7752                  controlled value which will usually be the address
 7753                  of the interface "closest to" the remote end. This
 7754                  address must appear in the remote end's
 7755                  <command>allow-transfer</command> option for the
 7756                  zone being transferred, if one is specified. This
 7757                  statement sets the
 7758                  <command>transfer-source</command> for all zones,
 7759                  but can be overridden on a per-view or per-zone
 7760                  basis by including a
 7761                  <command>transfer-source</command> statement within
 7762                  the <command>view</command> or
 7763                  <command>zone</command> block in the configuration
 7764                  file.
 7765                </para>
 7766	        <note>
 7767	          <para>
 7768	            Solaris 2.5.1 and earlier does not support setting the
 7769		    source address for TCP sockets.
 7770	          </para>
 7771                </note>
 7772              </listitem>
 7773            </varlistentry>
 7774
 7775            <varlistentry>
 7776              <term><command>transfer-source-v6</command></term>
 7777              <listitem>
 7778                <para>
 7779                  The same as <command>transfer-source</command>,
 7780                  except zone transfers are performed using IPv6.
 7781                </para>
 7782              </listitem>
 7783            </varlistentry>
 7784
 7785            <varlistentry>
 7786              <term><command>alt-transfer-source</command></term>
 7787              <listitem>
 7788                <para>
 7789                  An alternate transfer source if the one listed in
 7790                  <command>transfer-source</command> fails and
 7791                  <command>use-alt-transfer-source</command> is
 7792                  set.
 7793                </para>
 7794		<note>
 7795		  If you do not wish the alternate transfer source
 7796		  to be used, you should set
 7797		  <command>use-alt-transfer-source</command>
 7798		  appropriately and you should not depend upon
 7799		  getting an answer back to the first refresh
 7800		  query.
 7801		</note>
 7802              </listitem>
 7803            </varlistentry>
 7804
 7805            <varlistentry>
 7806              <term><command>alt-transfer-source-v6</command></term>
 7807              <listitem>
 7808                <para>
 7809                  An alternate transfer source if the one listed in
 7810                  <command>transfer-source-v6</command> fails and
 7811                  <command>use-alt-transfer-source</command> is
 7812                  set.
 7813                </para>
 7814              </listitem>
 7815            </varlistentry>
 7816
 7817            <varlistentry>
 7818              <term><command>use-alt-transfer-source</command></term>
 7819              <listitem>
 7820                <para>
 7821                  Use the alternate transfer sources or not.  If views are
 7822                  specified this defaults to <command>no</command>
 7823                  otherwise it defaults to
 7824                  <command>yes</command> (for BIND 8
 7825                  compatibility).
 7826                </para>
 7827              </listitem>
 7828            </varlistentry>
 7829
 7830            <varlistentry>
 7831              <term><command>notify-source</command></term>
 7832              <listitem>
 7833                <para><command>notify-source</command>
 7834		  determines which local source address, and
 7835                  optionally UDP port, will be used to send NOTIFY
 7836                  messages.  This address must appear in the slave
 7837                  server's <command>masters</command> zone clause or
 7838                  in an <command>allow-notify</command> clause.  This
 7839                  statement sets the <command>notify-source</command>
 7840                  for all zones, but can be overridden on a per-zone or
 7841                  per-view basis by including a
 7842                  <command>notify-source</command> statement within
 7843                  the <command>zone</command> or
 7844                  <command>view</command> block in the configuration
 7845                  file.
 7846                </para>
 7847	        <note>
 7848	          <para>
 7849	            Solaris 2.5.1 and earlier does not support setting the
 7850		    source address for TCP sockets.
 7851	          </para>
 7852                </note>
 7853              </listitem>
 7854            </varlistentry>
 7855
 7856            <varlistentry>
 7857              <term><command>notify-source-v6</command></term>
 7858              <listitem>
 7859                <para>
 7860                  Like <command>notify-source</command>,
 7861                  but applies to notify messages sent to IPv6 addresses.
 7862                </para>
 7863              </listitem>
 7864            </varlistentry>
 7865
 7866          </variablelist>
 7867
 7868        </sect3>
 7869
 7870        <sect3>
 7871          <title>UDP Port Lists</title>
 7872          <para>
 7873	    <command>use-v4-udp-ports</command>,
 7874	    <command>avoid-v4-udp-ports</command>,
 7875	    <command>use-v6-udp-ports</command>, and
 7876	    <command>avoid-v6-udp-ports</command>
 7877	    specify a list of IPv4 and IPv6 UDP ports that will be
 7878	    used or not used as source ports for UDP messages.
 7879	    See <xref linkend="query_address"/> about how the
 7880	    available ports are determined.
 7881	    For example, with the following configuration
 7882          </para>
 7883
 7884<programlisting>
 7885use-v6-udp-ports { range 32768 65535; };
 7886avoid-v6-udp-ports { 40000; range 50000 60000; };
 7887</programlisting>
 7888
 7889	   <para>
 7890	     UDP ports of IPv6 messages sent
 7891	     from <command>named</command> will be in one
 7892	     of the following ranges: 32768 to 39999, 40001 to 49999,
 7893	     and 60001 to 65535.
 7894	   </para>
 7895
 7896	   <para>
 7897	     <command>avoid-v4-udp-ports</command> and
 7898	     <command>avoid-v6-udp-ports</command> can be used
 7899             to prevent <command>named</command> from choosing as its random source port a
 7900             port that is blocked by your firewall or a port that is
 7901             used by other applications;
 7902	     if a query went out with a source port blocked by a
 7903             firewall, the
 7904	     answer would not get by the firewall and the name server would
 7905             have to query again.
 7906	     Note: the desired range can also be represented only with
 7907	     <command>use-v4-udp-ports</command> and
 7908	     <command>use-v6-udp-ports</command>, and the
 7909	     <command>avoid-</command> options are redundant in that
 7910	     sense; they are provided for backward compatibility and
 7911	     to possibly simplify the port specification.
 7912	   </para>
 7913        </sect3>
 7914
 7915        <sect3>
 7916          <title>Operating System Resource Limits</title>
 7917
 7918          <para>
 7919            The server's usage of many system resources can be limited.
 7920            Scaled values are allowed when specifying resource limits.  For
 7921            example, <command>1G</command> can be used instead of
 7922            <command>1073741824</command> to specify a limit of
 7923            one
 7924            gigabyte. <command>unlimited</command> requests
 7925            unlimited use, or the
 7926            maximum available amount. <command>default</command>
 7927            uses the limit
 7928            that was in force when the server was started. See the description
 7929            of <command>size_spec</command> in <xref linkend="configuration_file_elements"/>.
 7930          </para>
 7931
 7932          <para>
 7933            The following options set operating system resource limits for
 7934            the name server process.  Some operating systems don't support
 7935            some or
 7936            any of the limits. On such systems, a warning will be issued if
 7937            the
 7938            unsupported limit is used.
 7939          </para>
 7940
 7941          <variablelist>
 7942
 7943            <varlistentry>
 7944              <term><command>coresize</command></term>
 7945              <listitem>
 7946                <para>
 7947                  The maximum size of a core dump. The default
 7948                  is <literal>default</literal>.
 7949                </para>
 7950              </listitem>
 7951            </varlistentry>
 7952
 7953            <varlistentry>
 7954              <term><command>datasize</command></term>
 7955              <listitem>
 7956                <para>
 7957                  The maximum amount of data memory the server
 7958                  may use. The default is <literal>default</literal>.
 7959                  This is a hard limit on server memory usage.
 7960                  If the server attempts to allocate memory in excess of this
 7961                  limit, the allocation will fail, which may in turn leave
 7962                  the server unable to perform DNS service.  Therefore,
 7963                  this option is rarely useful as a way of limiting the
 7964                  amount of memory used by the server, but it can be used
 7965                  to raise an operating system data size limit that is
 7966                  too small by default.  If you wish to limit the amount
 7967                  of memory used by the server, use the
 7968                  <command>max-cache-size</command> and
 7969                  <command>recursive-clients</command>
 7970                  options instead.
 7971                </para>
 7972              </listitem>
 7973            </varlistentry>
 7974
 7975            <varlistentry>
 7976              <term><command>files</command></term>
 7977              <listitem>
 7978                <para>
 7979                  The maximum number of files the server
 7980                  may have open concurrently. The default is <literal>unlimited</literal>.
 7981                </para>
 7982              </listitem>
 7983            </varlistentry>
 7984
 7985            <varlistentry>
 7986              <term><command>stacksize</command></term>
 7987              <listitem>
 7988                <para>
 7989                  The maximum amount of stack memory the server
 7990                  may use. The default is <literal>default</literal>.
 7991                </para>
 7992              </listitem>
 7993            </varlistentry>
 7994
 7995          </variablelist>
 7996
 7997        </sect3>
 7998
 7999        <sect3 id="server_resource_limits">
 8000          <title>Server  Resource Limits</title>
 8001
 8002          <para>
 8003            The following options set limits on the server's
 8004            resource consumption that are enforced internally by the
 8005            server rather than the operating system.
 8006          </para>
 8007
 8008          <variablelist>
 8009
 8010            <varlistentry>
 8011              <term><command>max-ixfr-log-size</command></term>
 8012              <listitem>
 8013                <para>
 8014                  This option is obsolete; it is accepted
 8015                  and ignored for BIND 8 compatibility.  The option
 8016                  <command>max-journal-size</command> performs a
 8017                  similar function in BIND 9.
 8018                </para>
 8019              </listitem>
 8020            </varlistentry>
 8021
 8022            <varlistentry>
 8023              <term><command>max-journal-size</command></term>
 8024              <listitem>
 8025                <para>
 8026                  Sets a maximum size for each journal file
 8027                  (see <xref linkend="journal"/>).  When the journal file
 8028                  approaches
 8029                  the specified size, some of the oldest transactions in the
 8030                  journal
 8031                  will be automatically removed.  The default is
 8032                  <literal>unlimited</literal>.
 8033                  This may also be set on a per-zone basis.
 8034                </para>
 8035              </listitem>
 8036            </varlistentry>
 8037
 8038            <varlistentry>
 8039              <term><command>host-statistics-max</command></term>
 8040              <listitem>
 8041                <para>
 8042                  In BIND 8, specifies the maximum number of host statistics
 8043                  entries to be kept.
 8044                  Not implemented in BIND 9.
 8045                </para>
 8046              </listitem>
 8047            </varlistentry>
 8048
 8049            <varlistentry>
 8050              <term><command>recursive-clients</command></term>
 8051              <listitem>
 8052                <para>
 8053                  The maximum number of simultaneous recursive lookups
 8054                  the server will perform on behalf of clients.  The default
 8055                  is
 8056                  <literal>1000</literal>.  Because each recursing
 8057                  client uses a fair
 8058                  bit of memory, on the order of 20 kilobytes, the value of
 8059                  the
 8060                  <command>recursive-clients</command> option may
 8061                  have to be decreased
 8062                  on hosts with limited memory.
 8063                </para>
 8064              </listitem>
 8065            </varlistentry>
 8066
 8067            <varlistentry>
 8068              <term><command>tcp-clients</command></term>
 8069              <listitem>
 8070                <para>
 8071                  The maximum number of simultaneous client TCP
 8072                  connections that the server will accept.
 8073                  The default is <literal>100</literal>.
 8074                </para>
 8075              </listitem>
 8076            </varlistentry>
 8077
 8078            <varlistentry>
 8079              <term><command>reserved-sockets</command></term>
 8080              <listitem>
 8081                <para>
 8082		  The number of file descriptors reserved for TCP, stdio,
 8083		  etc.  This needs to be big enough to cover the number of
 8084		  interfaces <command>named</command> listens on, <command>tcp-clients</command> as well as
 8085		  to provide room for outgoing TCP queries and incoming zone
 8086		  transfers.  The default is <literal>512</literal>.
 8087		  The minimum value is <literal>128</literal> and the
 8088		  maximum value is <literal>128</literal> less than
 8089		  maxsockets (-S).  This option may be removed in the future.
 8090                </para>
 8091                <para>
 8092		  This option has little effect on Windows.
 8093                </para>
 8094              </listitem>
 8095            </varlistentry>
 8096
 8097            <varlistentry>
 8098              <term><command>max-cache-size</command></term>
 8099              <listitem>
 8100                <para>
 8101                  The maximum amount of memory to use for the
 8102                  server's cache, in bytes.
 8103                  When the amount of data in the cache
 8104                  reaches this limit, the server will cause records to expire
 8105                  prematurely based on an LRU based strategy so that
 8106                  the limit is not exceeded.
 8107                  A value of 0 is special, meaning that
 8108                  records are purged from the cache only when their
 8109                  TTLs expire.
 8110                  Another special keyword <userinput>unlimited</userinput>
 8111                  means the maximum value of 32-bit unsigned integers
 8112                  (0xffffffff), which may not have the same effect as
 8113                  0 on machines that support more than 32 bits of
 8114                  memory space.
 8115                  Any positive values less than 2MB will be ignored reset
 8116                  to 2MB.
 8117                  In a server with multiple views, the limit applies
 8118                  separately to the cache of each view.
 8119                  The default is 0.
 8120                </para>
 8121              </listitem>
 8122            </varlistentry>
 8123
 8124            <varlistentry>
 8125              <term><command>tcp-listen-queue</command></term>
 8126              <listitem>
 8127                <para>
 8128                  The listen queue depth.  The default and minimum is 3.
 8129                  If the kernel supports the accept filter "dataready" this
 8130                  also controls how
 8131                  many TCP connections that will be queued in kernel space
 8132                  waiting for
 8133                  some data before being passed to accept.  Values less than 3
 8134                  will be
 8135                  silently raised.
 8136                </para>
 8137              </listitem>
 8138            </varlistentry>
 8139
 8140          </variablelist>
 8141
 8142        </sect3>
 8143
 8144        <sect3>
 8145          <title>Periodic Task Intervals</title>
 8146
 8147          <variablelist>
 8148
 8149            <varlistentry>
 8150              <term><command>cleaning-interval</command></term>
 8151              <listitem>
 8152                <para>
 8153		  This interval is effectively obsolete.  Previously,
 8154		  the server would remove expired resource records
 8155                  from the cache every <command>cleaning-interval</command> minutes.
 8156		  <acronym>BIND</acronym> 9 now manages cache
 8157		  memory in a more sophisticated manner and does not
 8158		  rely on the periodic cleaning any more.
 8159		  Specifying this option therefore has no effect on
 8160		  the server's behavior.
 8161                </para>
 8162              </listitem>
 8163            </varlistentry>
 8164
 8165            <varlistentry>
 8166              <term><command>heartbeat-interval</command></term>
 8167              <listitem>
 8168                <para>
 8169                  The server will perform zone maintenance tasks
 8170                  for all zones marked as <command>dialup</command> whenever this
 8171                  interval expires. The default is 60 minutes. Reasonable
 8172                  values are up
 8173                  to 1 day (1440 minutes).  The maximum value is 28 days
 8174                  (40320 minutes).
 8175                  If set to 0, no zone maintenance for these zones will occur.
 8176                </para>
 8177              </listitem>
 8178            </varlistentry>
 8179
 8180            <varlistentry>
 8181              <term><command>interface-interval</command></term>
 8182              <listitem>
 8183                <para>
 8184                  The server will scan the network interface list
 8185                  every <command>interface-interval</command>
 8186                  minutes. The default
 8187                  is 60 minutes. The maximum value is 28 days (40320 minutes).
 8188                  If set to 0, interface scanning will only occur when
 8189                  the configuration file is  loaded. After the scan, the
 8190                  server will
 8191                  begin listening for queries on any newly discovered
 8192                  interfaces (provided they are allowed by the
 8193                  <command>listen-on</command> configuration), and
 8194                  will
 8195                  stop listening on interfaces that have gone away.
 8196                </para>
 8197              </listitem>
 8198            </varlistentry>
 8199
 8200            <varlistentry>
 8201              <term><command>statistics-interval</command></term>
 8202              <listitem>
 8203                <para>
 8204                  Name server statistics will be logged
 8205                  every <command>statistics-interval</command>
 8206                  minutes. The default is
 8207                  60. The maximum value is 28 days (40320 minutes).
 8208                  If set to 0, no statistics will be logged.
 8209                  </para><note>
 8210                  <simpara>
 8211                    Not yet implemented in
 8212                    <acronym>BIND</acronym> 9.
 8213                  </simpara>
 8214                </note>
 8215              </listitem>
 8216            </varlistentry>
 8217
 8218          </variablelist>
 8219
 8220        </sect3>
 8221
 8222        <sect3 id="topology">
 8223          <title>Topology</title>
 8224
 8225          <para>
 8226            All other things being equal, when the server chooses a name
 8227            server
 8228            to query from a list of name servers, it prefers the one that is
 8229            topologically closest to itself. The <command>topology</command> statement
 8230            takes an <command>address_match_list</command> and
 8231            interprets it
 8232            in a special way. Each top-level list element is assigned a
 8233            distance.
 8234            Non-negated elements get a distance based on their position in the
 8235            list, where the closer the match is to the start of the list, the
 8236            shorter the distance is between it and the server. A negated match
 8237            will be assigned the maximum distance from the server. If there
 8238            is no match, the address will get a distance which is further than
 8239            any non-negated list element, and closer than any negated element.
 8240            For example,
 8241          </para>
 8242
 8243<programlisting>topology {
 8244    10/8;
 8245    !1.2.3/24;
 8246    { 1.2/16; 3/8; };
 8247};</programlisting>
 8248
 8249          <para>
 8250            will prefer servers on network 10 the most, followed by hosts
 8251            on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the
 8252            exception of hosts on network 1.2.3 (netmask 255.255.255.0), which
 8253            is preferred least of all.
 8254          </para>
 8255          <para>
 8256            The default topology is
 8257          </para>
 8258
 8259<programlisting>    topology { localhost; localnets; };
 8260</programlisting>
 8261
 8262          <note>
 8263            <simpara>
 8264              The <command>topology</command> option
 8265              is not implemented in <acronym>BIND</acronym> 9.
 8266            </simpara>
 8267          </note>
 8268        </sect3>
 8269
 8270        <sect3 id="the_sortlist_statement">
 8271
 8272          <title>The <command>sortlist</command> Statement</title>
 8273
 8274          <para>
 8275            The response to a DNS query may consist of multiple resource
 8276            records (RRs) forming a resource records set (RRset).
 8277            The name server will normally return the
 8278            RRs within the RRset in an indeterminate order
 8279            (but see the <command>rrset-order</command>
 8280            statement in <xref linkend="rrset_ordering"/>).
 8281            The client resolver code should rearrange the RRs as appropriate,
 8282            that is, using any addresses on the local net in preference to
 8283            other addresses.
 8284            However, not all resolvers can do this or are correctly
 8285            configured.
 8286            When a client is using a local server, the sorting can be performed
 8287            in the server, based on the client's address. This only requires
 8288            configuring the name servers, not all the clients.
 8289          </para>
 8290
 8291          <para>
 8292            The <command>sortlist</command> statement (see below)
 8293            takes
 8294            an <command>address_match_list</command> and
 8295            interprets it even
 8296            more specifically than the <command>topology</command>
 8297            statement
 8298            does (<xref linkend="topology"/>).
 8299            Each top level statement in the <command>sortlist</command> must
 8300            itself be an explicit <command>address_match_list</command> with
 8301            one or two elements. The first element (which may be an IP
 8302            address,
 8303            an IP prefix, an ACL name or a nested <command>address_match_list</command>)
 8304            of each top level list is checked against the source address of
 8305            the query until a match is found.
 8306          </para>
 8307          <para>
 8308            Once the source address of the query has been matched, if
 8309            the top level statement contains only one element, the actual
 8310            primitive
 8311            element that matched the source address is used to select the
 8312            address
 8313            in the response to move to the beginning of the response. If the
 8314            statement is a list of two elements, then the second element is
 8315            treated the same as the <command>address_match_list</command> in
 8316            a <command>topology</command> statement. Each top
 8317            level element
 8318            is assigned a distance and the address in the response with the
 8319            minimum
 8320            distance is moved to the beginning of the response.
 8321          </para>
 8322          <para>
 8323            In the following example, any queries received from any of
 8324            the addresses of the host itself will get responses preferring
 8325            addresses
 8326            on any of the locally connected networks. Next most preferred are
 8327            addresses
 8328            on the 192.168.1/24 network, and after that either the
 8329            192.168.2/24
 8330            or
 8331            192.168.3/24 network with no preference shown between these two
 8332            networks. Queries received from a host on the 192.168.1/24 network
 8333            will prefer other addresses on that network to the 192.168.2/24
 8334            and
 8335            192.168.3/24 networks. Queries received from a host on the
 8336            192.168.4/24
 8337            or the 192.168.5/24 network will only prefer other addresses on
 8338            their directly connected networks.
 8339          </para>
 8340
 8341<programlisting>sortlist {
 8342    // IF the local host
 8343    // THEN first fit on the following nets
 8344    { localhost;
 8345        { localnets;
 8346            192.168.1/24;
 8347            { 192.168.2/24; 192.168.3/24; }; }; };
 8348    // IF on class C 192.168.1 THEN use .1, or .2 or .3
 8349    { 192.168.1/24;
 8350        { 192.168.1/24;
 8351            { 192.168.2/24; 192.168.3/24; }; }; };
 8352    // IF on class C 192.168.2 THEN use .2, or .1 or .3
 8353    { 192.168.2/24;
 8354        { 192.168.2/24;
 8355            { 192.168.1/24; 192.168.3/24; }; }; };
 8356    // IF on class C 192.168.3 THEN use .3, or .1 or .2
 8357    { 192.168.3/24;
 8358        { 192.168.3/24;
 8359            { 192.168.1/24; 192.168.2/24; }; }; };
 8360    // IF .4 or .5 THEN prefer that net
 8361    { { 192.168.4/24; 192.168.5/24; };
 8362    };
 8363};</programlisting>
 8364
 8365          <para>
 8366            The following example will give reasonable behavior for the
 8367            local host and hosts on directly connected networks. It is similar
 8368            to the behavior of the address sort in <acronym>BIND</acronym> 4.9.x. Responses sent
 8369            to queries from the local host will favor any of the directly
 8370            connected
 8371            networks. Responses sent to queries from any other hosts on a
 8372            directly
 8373            connected network will prefer addresses on that same network.
 8374            Responses
 8375            to other queries will not be sorted.
 8376          </para>
 8377
 8378<programlisting>sortlist {
 8379           { localhost; localnets; };
 8380           { localnets; };
 8381};
 8382</programlisting>
 8383
 8384        </sect3>
 8385        <sect3 id="rrset_ordering">
 8386          <title id="rrset_ordering_title">RRset Ordering</title>
 8387          <para>
 8388            When multiple records are returned in an answer it may be
 8389            useful to configure the order of the records placed into the
 8390            response.
 8391            The <command>rrset-order</command> statement permits
 8392            configuration
 8393            of the ordering of the records in a multiple record response.
 8394            See also the <command>sortlist</command> statement,
 8395            <xref linkend="the_sortlist_statement"/>.
 8396          </para>
 8397
 8398          <para>
 8399            An <command>order_spec</command> is defined as
 8400            follows:
 8401          </para>
 8402          <para>
 8403	    <optional>class <replaceable>class_name</replaceable></optional>
 8404            <optional>type <replaceable>type_name</replaceable></optional>
 8405            <optional>name <replaceable>"domain_name"</replaceable></optional>
 8406	    order <replaceable>ordering</replaceable>
 8407	  </para>
 8408          <para>
 8409            If no class is specified, the default is <command>ANY</command>.
 8410            If no type is specified, the default is <command>ANY</command>.
 8411            If no name is specified, the default is "<command>*</command>" (asterisk).
 8412          </para>
 8413          <para>
 8414            The legal values for <command>ordering</command> are:
 8415          </para>
 8416          <informaltable colsep="0" rowsep="0">
 8417            <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 8418              <colspec colname="1" colnum="1" colsep="0" colwidth="0.750in"/>
 8419              <colspec colname="2" colnum="2" colsep="0" colwidth="3.750in"/>
 8420              <tbody>
 8421                <row rowsep="0">
 8422                  <entry colname="1">
 8423                    <para><command>fixed</command></para>
 8424                  </entry>
 8425                  <entry colname="2">
 8426                    <para>
 8427                      Records are returned in the order they
 8428                      are defined in the zone file.
 8429                    </para>
 8430                  </entry>
 8431                </row>
 8432                <row rowsep="0">
 8433                  <entry colname="1">
 8434                    <para><command>random</command></para>
 8435                  </entry>
 8436                  <entry colname="2">
 8437                    <para>
 8438                      Records are returned in some random order.
 8439                    </para>
 8440                  </entry>
 8441                </row>
 8442                <row rowsep="0">
 8443                  <entry colname="1">
 8444                    <para><command>cyclic</command></para>
 8445                  </entry>
 8446                  <entry colname="2">
 8447                    <para>
 8448                      Records are returned in a cyclic round-robin order.
 8449                    </para>
 8450                    <para>
 8451                      If <acronym>BIND</acronym> is configured with the
 8452                      "--enable-fixed-rrset" option at compile time, then
 8453                      the initial ordering of the RRset will match the
 8454                      one specified in the zone file.
 8455                    </para>
 8456                  </entry>
 8457                </row>
 8458              </tbody>
 8459            </tgroup>
 8460          </informaltable>
 8461          <para>
 8462            For example:
 8463          </para>
 8464
 8465<programlisting>rrset-order {
 8466   class IN type A name "host.example.com" order random;
 8467   order cyclic;
 8468};
 8469</programlisting>
 8470
 8471          <para>
 8472            will cause any responses for type A records in class IN that
 8473            have "<literal>host.example.com</literal>" as a
 8474            suffix, to always be returned
 8475            in random order. All other records are returned in cyclic order.
 8476          </para>
 8477          <para>
 8478            If multiple <command>rrset-order</command> statements
 8479            appear,
 8480            they are not combined &mdash; the last one applies.
 8481          </para>
 8482
 8483          <note>
 8484            <simpara>
 8485              In this release of <acronym>BIND</acronym> 9, the
 8486              <command>rrset-order</command> statement does not support
 8487              "fixed" ordering by default.  Fixed ordering can be enabled
 8488              at compile time by specifying "--enable-fixed-rrset" on
 8489              the "configure" command line.
 8490            </simpara>
 8491          </note>
 8492        </sect3>
 8493
 8494        <sect3 id="tuning">
 8495          <title>Tuning</title>
 8496
 8497          <variablelist>
 8498
 8499            <varlistentry>
 8500              <term><command>lame-ttl</command></term>
 8501              <listitem>
 8502                <para>
 8503                  Sets the number of seconds to cache a
 8504                  lame server indication. 0 disables caching. (This is
 8505                  <emphasis role="bold">NOT</emphasis> recommended.)
 8506                  The default is <literal>600</literal> (10 minutes) and the
 8507                  maximum value is
 8508                  <literal>1800</literal> (30 minutes).
 8509                </para>
 8510
 8511		<para>
 8512		  Lame-ttl also controls the amount of time DNSSEC
 8513		  validation failures are cached.  There is a minimum
 8514		  of 30 seconds applied to bad cache entries if the
 8515		  lame-ttl is set to less than 30 seconds.
 8516		</para>
 8517
 8518              </listitem>
 8519            </varlistentry>
 8520
 8521            <varlistentry>
 8522              <term><command>max-ncache-ttl</command></term>
 8523              <listitem>
 8524                <para>
 8525                  To reduce network traffic and increase performance,
 8526                  the server stores negative answers. <command>max-ncache-ttl</command> is
 8527                  used to set a maximum retention time for these answers in
 8528                  the server
 8529                  in seconds. The default
 8530                  <command>max-ncache-ttl</command> is <literal>10800</literal> seconds (3 hours).
 8531                  <command>max-ncache-ttl</command> cannot exceed
 8532                  7 days and will
 8533                  be silently truncated to 7 days if set to a greater value.
 8534                </para>
 8535              </listitem>
 8536            </varlistentry>
 8537
 8538            <varlistentry>
 8539              <term><command>max-cache-ttl</command></term>
 8540              <listitem>
 8541                <para>
 8542		  Sets the maximum time for which the server will
 8543                  cache ordinary (positive) answers. The default is
 8544                  one week (7 days).
 8545		  A value of zero may cause all queries to return
 8546		  SERVFAIL, because of lost caches of intermediate
 8547		  RRsets (such as NS and glue AAAA/A records) in the
 8548		  resolution process.
 8549                </para>
 8550              </listitem>
 8551            </varlistentry>
 8552
 8553            <varlistentry>
 8554              <term><command>min-roots</command></term>
 8555              <listitem>
 8556                <para>
 8557                  The minimum number of root servers that
 8558                  is required for a request for the root servers to be
 8559                  accepted. The default
 8560                  is <userinput>2</userinput>.
 8561                </para>
 8562                <note>
 8563                  <simpara>
 8564                    Not implemented in <acronym>BIND</acronym> 9.
 8565                  </simpara>
 8566                </note>
 8567              </listitem>
 8568            </varlistentry>
 8569
 8570	    <varlistentry>
 8571	      <term><command>sig-validity-interval</command></term>
 8572	      <listitem>
 8573		<para>
 8574		  Specifies the number of days into the future when
 8575		  DNSSEC signatures automatically generated as a
 8576		  result of dynamic updates (<xref
 8577		  linkend="dynamic_update"/>) will expire.  There
 8578		  is an optional second field which specifies how
 8579		  long before expiry that the signatures will be
 8580		  regenerated.  If not specified, the signatures will
 8581		  be regenerated at 1/4 of base interval.  The second
 8582		  field is specified in days if the base interval is
 8583		  greater than 7 days otherwise it is specified in hours.
 8584		  The default base interval is <literal>30</literal> days
 8585		  giving a re-signing interval of 7 1/2 days.  The maximum
 8586		  values are 10 years (3660 days).
 8587		</para>
 8588		<para>
 8589		  The signature inception time is unconditionally
 8590		  set to one hour before the current time to allow
 8591		  for a limited amount of clock skew.
 8592		</para>
 8593		<para>
 8594		  The <command>sig-validity-interval</command>
 8595		  should be, at least, several multiples of the SOA
 8596		  expire interval to allow for reasonable interaction
 8597		  between the various timer and expiry dates.
 8598		</para>
 8599	      </listitem>
 8600	    </varlistentry>
 8601
 8602	    <varlistentry>
 8603	      <term><command>sig-signing-nodes</command></term>
 8604	      <listitem>
 8605		<para>
 8606		  Specify the maximum number of nodes to be
 8607		  examined in each quantum when signing a zone with
 8608		  a new DNSKEY. The default is
 8609		  <literal>100</literal>.
 8610		</para>
 8611	      </listitem>
 8612	    </varlistentry>
 8613
 8614	    <varlistentry>
 8615	      <term><command>sig-signing-signatures</command></term>
 8616	      <listitem>
 8617		<para>
 8618		  Specify a threshold number of signatures that
 8619		  will terminate processing a quantum when signing
 8620		  a zone with a new DNSKEY.  The default is
 8621		  <literal>10</literal>.
 8622		</para>
 8623	      </listitem>
 8624	    </varlistentry>
 8625
 8626	    <varlistentry>
 8627	      <term><command>sig-signing-type</command></term>
 8628	      <listitem>
 8629		<para>
 8630		  Specify a private RDATA type to be used when generating
 8631		  key signing records.  The default is
 8632		  <literal>65534</literal>.
 8633		</para>
 8634		<para>
 8635		  It is expected that this parameter may be removed
 8636		  in a future version once there is a standard type.
 8637		</para>
 8638	      </listitem>
 8639	    </varlistentry>
 8640
 8641            <varlistentry>
 8642              <term><command>min-refresh-time</command></term>
 8643              <term><command>max-refresh-time</command></term>
 8644              <term><command>min-retry-time</command></term>
 8645              <term><command>max-retry-time</command></term>
 8646              <listitem>
 8647                <para>
 8648                  These options control the server's behavior on refreshing a
 8649                  zone
 8650                  (querying for SOA changes) or retrying failed transfers.
 8651                  Usually the SOA values for the zone are used, but these
 8652                  values
 8653                  are set by the master, giving slave server administrators
 8654                  little
 8655                  control over their contents.
 8656                </para>
 8657                <para>
 8658                  These options allow the administrator to set a minimum and
 8659                  maximum
 8660                  refresh and retry time either per-zone, per-view, or
 8661                  globally.
 8662                  These options are valid for slave and stub zones,
 8663                  and clamp the SOA refresh and retry times to the specified
 8664                  values.
 8665                </para>
 8666		<para>
 8667		  The following defaults apply.
 8668		  <command>min-refresh-time</command> 300 seconds,
 8669		  <command>max-refresh-time</command> 2419200 seconds
 8670		  (4 weeks), <command>min-retry-time</command> 500 seconds,
 8671		  and <command>max-retry-time</command> 1209600 seconds
 8672		  (2 weeks).
 8673		</para>
 8674              </listitem>
 8675            </varlistentry>
 8676
 8677            <varlistentry>
 8678              <term><command>edns-udp-size</command></term>
 8679              <listitem>
 8680                <para>
 8681		  Sets the advertised EDNS UDP buffer size in bytes
 8682                  to control the size of packets received.
 8683                  Valid values are 512 to 4096 (values outside this range
 8684		  will be silently adjusted).  The default value
 8685		  is 4096.  The usual reason for setting
 8686		  <command>edns-udp-size</command> to a non-default
 8687		  value is to get UDP answers to pass through broken
 8688		  firewalls that block fragmented packets and/or
 8689		  block UDP packets that are greater than 512 bytes.
 8690                </para>
 8691		<para>
 8692		  <command>named</command> will fallback to using 512 bytes
 8693		  if it get a series of timeout at the initial value.  512
 8694		  bytes is not being offered to encourage sites to fix their
 8695	          firewalls.  Small EDNS UDP sizes will result in the
 8696		  excessive use of TCP.
 8697		</para>
 8698              </listitem>
 8699            </varlistentry>
 8700
 8701            <varlistentry>
 8702              <term><command>max-udp-size</command></term>
 8703	      <listitem>
 8704		<para>
 8705		  Sets the maximum EDNS UDP message size
 8706		  <command>named</command> will send in bytes.
 8707		  Valid values are 512 to 4096 (values outside this
 8708		  range will be silently adjusted).  The default
 8709		  value is 4096.  The usual reason for setting
 8710		  <command>max-udp-size</command> to a non-default
 8711		  value is to get UDP answers to pass through broken
 8712		  firewalls that block fragmented packets and/or
 8713		  block UDP packets that are greater than 512 bytes.
 8714		  This is independent of the advertised receive
 8715		  buffer (<command>edns-udp-size</command>).
 8716		</para>
 8717		<para>
 8718		  Setting this to a low value will encourage additional
 8719		  TCP traffic to the nameserver.
 8720		</para>
 8721	      </listitem>
 8722	    </varlistentry>
 8723
 8724	    <varlistentry>
 8725	      <term><command>masterfile-format</command></term>
 8726	      <listitem>
 8727	        <para>Specifies
 8728		  the file format of zone files (see
 8729	          <xref linkend="zonefile_format"/>).
 8730	          The default value is <constant>text</constant>, which is the
 8731		  standard textual representation.  Files in other formats
 8732		  than <constant>text</constant> are typically expected
 8733		  to be generated by the <command>named-compilezone</command> tool.
 8734		  Note that when a zone file in a different format than
 8735		  <constant>text</constant> is loaded, <command>named</command>
 8736	          may omit some of the checks which would be performed for a
 8737		  file in the <constant>text</constant> format.  In particular,
 8738		  <command>check-names</command> checks do not apply
 8739		  for the <constant>raw</constant> format.  This means
 8740		  a zone file in the <constant>raw</constant> format
 8741		  must be generated with the same check level as that
 8742		  specified in the <command>named</command> configuration
 8743		  file.  This statement sets the
 8744		  <command>masterfile-format</command> for all zones,
 8745		  but can be overridden on a per-zone or per-view basis
 8746		  by including a <command>masterfile-format</command>
 8747		  statement within the <command>zone</command> or
 8748		  <command>view</command> block in the configuration
 8749		  file.
 8750	        </para>
 8751	      </listitem>
 8752	    </varlistentry>
 8753
 8754	    <varlistentry id="clients-per-query">
 8755	      <term><command>clients-per-query</command></term>
 8756	      <term><command>max-clients-per-query</command></term>
 8757              <listitem>
 8758		<para>These set the
 8759		  initial value (minimum) and maximum number of recursive
 8760		  simultaneous clients for any given query
 8761		  (&lt;qname,qtype,qclass&gt;) that the server will accept
 8762		  before dropping additional clients.  <command>named</command> will attempt to
 8763		  self tune this value and changes will be logged.  The
 8764		  default values are 10 and 100.
 8765		</para>
 8766		<para>
 8767	          This value should reflect how many queries come in for
 8768		  a given name in the time it takes to resolve that name.
 8769		  If the number of queries exceed this value, <command>named</command> will
 8770		  assume that it is dealing with a non-responsive zone
 8771		  and will drop additional queries.  If it gets a response
 8772		  after dropping queries, it will raise the estimate.  The
 8773		  estimate will then be lowered in 20 minutes if it has
 8774		  remained unchanged.
 8775		</para>
 8776		<para>
 8777		  If <command>clients-per-query</command> is set to zero,
 8778		  then there is no limit on the number of clients per query
 8779		  and no queries will be dropped.
 8780		</para>
 8781		<para>
 8782		  If <command>max-clients-per-query</command> is set to zero,
 8783		  then there is no upper bound other than imposed by
 8784		  <command>recursive-clients</command>.
 8785		</para>
 8786              </listitem>
 8787	    </varlistentry>
 8788
 8789            <varlistentry>
 8790              <term><command>notify-delay</command></term>
 8791              <listitem>
 8792                <para>
 8793                  The delay, in seconds, between sending sets of notify
 8794                  messages for a zone.  The default is five (5) seconds.
 8795                </para>
 8796                <para>
 8797		  The overall rate that NOTIFY messages are sent for all
 8798		  zones is controlled by <command>serial-query-rate</command>.
 8799		</para>
 8800              </listitem>
 8801            </varlistentry>
 8802	  </variablelist>
 8803
 8804        </sect3>
 8805
 8806        <sect3 id="builtin">
 8807          <title>Built-in server information zones</title>
 8808
 8809          <para>
 8810            The server provides some helpful diagnostic information
 8811            through a number of built-in zones under the
 8812            pseudo-top-level-domain <literal>bind</literal> in the
 8813            <command>CHAOS</command> class.  These zones are part
 8814            of a
 8815            built-in view (see <xref linkend="view_statement_grammar"/>) of
 8816            class
 8817            <command>CHAOS</command> which is separate from the
 8818            default view of
 8819            class <command>IN</command>; therefore, any global
 8820            server options
 8821            such as <command>allow-query</command> do not apply
 8822            the these zones.
 8823            If you feel the need to disable these zones, use the options
 8824            below, or hide the built-in <command>CHAOS</command>
 8825            view by
 8826            defining an explicit view of class <command>CHAOS</command>
 8827            that matches all clients.
 8828          </para>
 8829
 8830          <variablelist>
 8831
 8832            <varlistentry>
 8833              <term><command>version</command></term>
 8834              <listitem>
 8835                <para>
 8836                  The version the server should report
 8837                  via a query of the name <literal>version.bind</literal>
 8838                  with type <command>TXT</command>, class <command>CHAOS</command>.
 8839                  The default is the real version number of this server.
 8840                  Specifying <command>version none</command>
 8841                  disables processing of the queries.
 8842                </para>
 8843              </listitem>
 8844            </varlistentry>
 8845
 8846            <varlistentry>
 8847              <term><command>hostname</command></term>
 8848              <listitem>
 8849                <para>
 8850                  The hostname the server should report via a query of
 8851                  the name <filename>hostname.bind</filename>
 8852                  with type <command>TXT</command>, class <command>CHAOS</command>.
 8853                  This defaults to the hostname of the machine hosting the
 8854                  name server as
 8855                  found by the gethostname() function.  The primary purpose of such queries
 8856                  is to
 8857                  identify which of a group of anycast servers is actually
 8858                  answering your queries.  Specifying <command>hostname none;</command>
 8859                  disables processing of the queries.
 8860                </para>
 8861              </listitem>
 8862            </varlistentry>
 8863
 8864            <varlistentry>
 8865              <term><command>server-id</command></term>
 8866              <listitem>
 8867                <para>
 8868                  The ID the server should report when receiving a Name
 8869                  Server Identifier (NSID) query, or a query of the name
 8870                  <filename>ID.SERVER</filename> with type
 8871                  <command>TXT</command>, class <command>CHAOS</command>.
 8872                  The primary purpose of such queries is to
 8873                  identify which of a group of anycast servers is actually
 8874                  answering your queries.  Specifying <command>server-id none;</command>
 8875                  disables processing of the queries.
 8876                  Specifying <command>server-id hostname;</command> will cause <command>named</command> to
 8877                  use the hostname as found by the gethostname() function.
 8878                  The default <command>server-id</command> is <command>none</command>.
 8879                </para>
 8880              </listitem>
 8881            </varlistentry>
 8882
 8883          </variablelist>
 8884
 8885        </sect3>
 8886
 8887        <sect3 id="empty">
 8888          <title>Built-in Empty Zones</title>
 8889	  <para>
 8890	    Named has some built-in empty zones (SOA and NS records only).
 8891	    These are for zones that should normally be answered locally
 8892	    and which queries should not be sent to the Internet's root
 8893	    servers.  The official servers which cover these namespaces
 8894	    return NXDOMAIN responses to these queries.  In particular,
 8895            these cover the reverse namespaces for addresses from
 8896            RFC 1918, RFC 4193, and RFC 5737.  They also include the
 8897            reverse namespace for IPv6 local address (locally assigned),
 8898            IPv6 link local addresses, the IPv6 loopback address and the
 8899            IPv6 unknown address.
 8900	  </para>
 8901	  <para>
 8902	    Named will attempt to determine if a built-in zone already exists
 8903	    or is active (covered by a forward-only forwarding declaration)
 8904	    and will not create an empty zone in that case.
 8905	  </para>
 8906	  <para>
 8907	    The current list of empty zones is:
 8908	    <itemizedlist>
 8909	      <listitem>10.IN-ADDR.ARPA</listitem>
 8910	      <listitem>16.172.IN-ADDR.ARPA</listitem>
 8911	      <listitem>17.172.IN-ADDR.ARPA</listitem>
 8912	      <listitem>18.172.IN-ADDR.ARPA</listitem>
 8913	      <listitem>19.172.IN-ADDR.ARPA</listitem>
 8914	      <listitem>20.172.IN-ADDR.ARPA</listitem>
 8915	      <listitem>21.172.IN-ADDR.ARPA</listitem>
 8916	      <listitem>22.172.IN-ADDR.ARPA</listitem>
 8917	      <listitem>23.172.IN-ADDR.ARPA</listitem>
 8918	      <listitem>24.172.IN-ADDR.ARPA</listitem>
 8919	      <listitem>25.172.IN-ADDR.ARPA</listitem>
 8920	      <listitem>26.172.IN-ADDR.ARPA</listitem>
 8921	      <listitem>27.172.IN-ADDR.ARPA</listitem>
 8922	      <listitem>28.172.IN-ADDR.ARPA</listitem>
 8923	      <listitem>29.172.IN-ADDR.ARPA</listitem>
 8924	      <listitem>30.172.IN-ADDR.ARPA</listitem>
 8925	      <listitem>31.172.IN-ADDR.ARPA</listitem>
 8926	      <listitem>168.192.IN-ADDR.ARPA</listitem>
 8927	      <listitem>0.IN-ADDR.ARPA</listitem>
 8928	      <listitem>127.IN-ADDR.ARPA</listitem>
 8929	      <listitem>254.169.IN-ADDR.ARPA</listitem>
 8930	      <listitem>2.0.192.IN-ADDR.ARPA</listitem>
 8931	      <listitem>100.51.198.IN-ADDR.ARPA</listitem>
 8932	      <listitem>113.0.203.IN-ADDR.ARPA</listitem>
 8933	      <listitem>255.255.255.255.IN-ADDR.ARPA</listitem>
 8934	      <listitem>0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</listitem>
 8935	      <listitem>1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</listitem>
 8936	      <listitem>8.B.D.0.1.0.0.2.IP6.ARPA</listitem>
 8937	      <listitem>D.F.IP6.ARPA</listitem>
 8938	      <listitem>8.E.F.IP6.ARPA</listitem>
 8939	      <listitem>9.E.F.IP6.ARPA</listitem>
 8940	      <listitem>A.E.F.IP6.ARPA</listitem>
 8941	      <listitem>B.E.F.IP6.ARPA</listitem>
 8942	    </itemizedlist>
 8943	  </para>
 8944	  <para>
 8945	    Empty zones are settable at the view level and only apply to
 8946	    views of class IN.  Disabled empty zones are only inherited
 8947	    from options if there are no disabled empty zones specified
 8948	    at the view level.  To override the options list of disabled
 8949	    zones, you can disable the root zone at the view level, for example:
 8950<programlisting>
 8951	    disable-empty-zone ".";
 8952</programlisting>
 8953	  </para>
 8954	  <para>
 8955	    If you are using the address ranges covered here, you should
 8956	    already have reverse zones covering the addresses you use.
 8957	    In practice this appears to not be the case with many queries
 8958	    being made to the infrastructure servers for names in these
 8959	    spaces.  So many in fact that sacrificial servers were needed
 8960	    to be deployed to channel the query load away from the
 8961	    infrastructure servers.
 8962	  </para>
 8963	  <note>
 8964	    The real parent servers for these zones should disable all
 8965	    empty zone under the parent zone they serve.  For the real
 8966	    root servers, this is all built-in empty zones.  This will
 8967	    enable them to return referrals to deeper in the tree.
 8968	  </note>
 8969          <variablelist>
 8970	    <varlistentry>
 8971	      <term><command>empty-server</command></term>
 8972	      <listitem>
 8973	        <para>
 8974		  Specify what server name will appear in the returned
 8975		  SOA record for empty zones.  If none is specified, then
 8976		  the zone's name will be used.
 8977	        </para>
 8978	       </listitem>
 8979	    </varlistentry>
 8980	      
 8981	    <varlistentry>
 8982	      <term><command>empty-contact</command></term>
 8983	      <listitem>
 8984	        <para>
 8985		  Specify what contact name will appear in the returned
 8986		  SOA record for empty zones.  If none is specified, then
 8987		  "." will be used.
 8988	        </para>
 8989	      </listitem>
 8990	    </varlistentry>
 8991  
 8992	    <varlistentry>
 8993	      <term><command>empty-zones-enable</command></term>
 8994	      <listitem>
 8995	        <para>
 8996		  Enable or disable all empty zones.  By default, they
 8997		  are enabled.
 8998	        </para>
 8999	      </listitem>
 9000	    </varlistentry>
 9001  
 9002	    <varlistentry>
 9003	    <term><command>disable-empty-zone</command></term>
 9004	      <listitem>
 9005	        <para>
 9006		  Disable individual empty zones.  By default, none are
 9007		  disabled.  This option can be specified multiple times.
 9008	        </para>
 9009	      </listitem>
 9010	    </varlistentry>
 9011          </variablelist>
 9012        </sect3>
 9013
 9014        <sect3 id="acache">
 9015          <title>Additional Section Caching</title>
 9016
 9017          <para>
 9018            The additional section cache, also called <command>acache</command>,
 9019            is an internal cache to improve the response performance of BIND 9.
 9020            When additional section caching is enabled, BIND 9 will
 9021            cache an internal short-cut to the additional section content for
 9022            each answer RR.
 9023            Note that <command>acache</command> is an internal caching
 9024            mechanism of BIND 9, and is not related to the DNS caching
 9025            server function.
 9026          </para>
 9027
 9028          <para>
 9029            Additional section caching does not change the
 9030            response content (except the RRsets ordering of the additional
 9031            section, see below), but can improve the response performance
 9032            significantly.
 9033            It is particularly effective when BIND 9 acts as an authoritative
 9034            server for a zone that has many delegations with many glue RRs.
 9035          </para>
 9036
 9037          <para>
 9038            In order to obtain the maximum performance improvement
 9039            from additional section caching, setting
 9040            <command>additional-from-cache</command>
 9041            to <command>no</command> is recommended, since the current
 9042            implementation of <command>acache</command>
 9043            does not short-cut of additional section information from the
 9044            DNS cache data.
 9045          </para><