"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/doc/arm/Bv9ARM-book.xml" (7 Sep 2020, 594615 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "Bv9ARM-book.xml": 9.11.21_vs_9.11.22.

    1 <!--
    2  - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  -
    4  - This Source Code Form is subject to the terms of the Mozilla Public
    5  - License, v. 2.0. If a copy of the MPL was not distributed with this
    6  - file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  -
    8  - See the COPYRIGHT file distributed with this work for additional
    9  - information regarding copyright ownership.
   10 -->
   11 
   12 <!-- Converted by db4-upgrade version 1.0 -->
   13 <book xmlns:db="http://docbook.org/ns/docbook" version="5.0">
   14   <info>
   15     <title>BIND 9 Administrator Reference Manual</title>
   16     <!-- insert copyright start -->
   17     <copyright>
   18       <year>2000</year>
   19       <year>2001</year>
   20       <year>2002</year>
   21       <year>2003</year>
   22       <year>2004</year>
   23       <year>2005</year>
   24       <year>2006</year>
   25       <year>2007</year>
   26       <year>2008</year>
   27       <year>2009</year>
   28       <year>2010</year>
   29       <year>2011</year>
   30       <year>2012</year>
   31       <year>2013</year>
   32       <year>2014</year>
   33       <year>2015</year>
   34       <year>2016</year>
   35       <year>2017</year>
   36       <year>2018</year>
   37       <year>2019</year>
   38       <year>2020</year>
   39       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
   40     </copyright>
   41     <!-- insert copyright end -->
   42     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="releaseinfo.xml"/>
   43   </info>
   44 
   45   <chapter xml:id="Bv9ARM.ch01"><info><title>Introduction</title></info>
   46 
   47     <para>
   48       The Internet Domain Name System (<acronym>DNS</acronym>)
   49       consists of the syntax
   50       to specify the names of entities in the Internet in a hierarchical
   51       manner, the rules used for delegating authority over names, and the
   52       system implementation that actually maps names to Internet
   53       addresses.  <acronym>DNS</acronym> data is maintained in a
   54       group of distributed
   55       hierarchical databases.
   56     </para>
   57 
   58     <section xml:id="doc_scope"><info><title>Scope of Document</title></info>
   59 
   60       <para>
   61     The Berkeley Internet Name Domain
   62     (<acronym>BIND</acronym>) implements a
   63     domain name server for a number of operating systems. This
   64     document provides basic information about the installation and
   65     care of the Internet Systems Consortium (<acronym>ISC</acronym>)
   66     <acronym>BIND</acronym> version 9 software package for
   67     system administrators.
   68       </para>
   69       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkgversion.xml"/>
   70     </section>
   71 
   72     <section xml:id="organization"><info><title>Organization of This Document</title></info>
   73 
   74       <para>
   75     In this document, <emphasis>Chapter 1</emphasis> introduces
   76     the basic <acronym>DNS</acronym> and <acronym>BIND</acronym> concepts. <emphasis>Chapter 2</emphasis>
   77     describes resource requirements for running <acronym>BIND</acronym> in various
   78     environments. Information in <emphasis>Chapter 3</emphasis> is
   79     <emphasis>task-oriented</emphasis> in its presentation and is
   80     organized functionally, to aid in the process of installing the
   81     <acronym>BIND</acronym> 9 software. The task-oriented
   82     section is followed by
   83     <emphasis>Chapter 4</emphasis>, which contains more advanced
   84     concepts that the system administrator may need for implementing
   85     certain options. <emphasis>Chapter 5</emphasis>
   86     describes the <acronym>BIND</acronym> 9 lightweight
   87     resolver.  The contents of <emphasis>Chapter 6</emphasis> are
   88     organized as in a reference manual to aid in the ongoing
   89     maintenance of the software. <emphasis>Chapter 7</emphasis> addresses
   90     security considerations, and
   91     <emphasis>Chapter 8</emphasis> contains troubleshooting help. The
   92     main body of the document is followed by several
   93     <emphasis>appendices</emphasis> which contain useful reference
   94     information, such as a <emphasis>bibliography</emphasis> and
   95     historic information related to <acronym>BIND</acronym>
   96     and the Domain Name
   97     System.
   98       </para>
   99     </section>
  100     <section xml:id="conventions"><info><title>Conventions Used in This Document</title></info>
  101 
  102       <para>
  103     In this document, we use the following general typographic
  104     conventions:
  105       </para>
  106 
  107       <informaltable>
  108     <tgroup cols="2">
  109       <colspec colname="1" colnum="1" colwidth="3.000in"/>
  110       <colspec colname="2" colnum="2" colwidth="2.625in"/>
  111       <tbody>
  112         <row>
  113           <entry colname="1">
  114         <para>
  115           <emphasis>To describe:</emphasis>
  116         </para>
  117           </entry>
  118           <entry colname="2">
  119         <para>
  120           <emphasis>We use the style:</emphasis>
  121         </para>
  122           </entry>
  123         </row>
  124         <row>
  125           <entry colname="1">
  126         <para>
  127           a pathname, filename, URL, hostname,
  128           mailing list name, or new term or concept
  129         </para>
  130           </entry>
  131           <entry colname="2">
  132         <para>
  133           <filename>Fixed width</filename>
  134         </para>
  135           </entry>
  136         </row>
  137         <row>
  138           <entry colname="1">
  139         <para>
  140           literal user
  141           input
  142         </para>
  143           </entry>
  144           <entry colname="2">
  145         <para>
  146           <userinput>Fixed Width Bold</userinput>
  147         </para>
  148           </entry>
  149         </row>
  150         <row>
  151           <entry colname="1">
  152         <para>
  153           program output
  154         </para>
  155           </entry>
  156           <entry colname="2">
  157         <para>
  158           <computeroutput>Fixed Width</computeroutput>
  159         </para>
  160           </entry>
  161         </row>
  162       </tbody>
  163     </tgroup>
  164       </informaltable>
  165 
  166       <para>
  167     The following conventions are used in descriptions of the
  168     <acronym>BIND</acronym> configuration file:<informaltable colsep="0" frame="all" rowsep="0">
  169           <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
  170               <colspec colname="1" colnum="1" colsep="0" colwidth="3.000in"/>
  171         <colspec colname="2" colnum="2" colsep="0" colwidth="2.625in"/>
  172         <tbody>
  173           <row rowsep="0">
  174         <entry colname="1" colsep="1" rowsep="1">
  175           <para>
  176             <emphasis>To describe:</emphasis>
  177           </para>
  178         </entry>
  179         <entry colname="2" rowsep="1">
  180           <para>
  181             <emphasis>We use the style:</emphasis>
  182           </para>
  183         </entry>
  184           </row>
  185           <row rowsep="0">
  186         <entry colname="1" colsep="1" rowsep="1">
  187           <para>
  188             keywords
  189           </para>
  190         </entry>
  191         <entry colname="2" rowsep="1">
  192           <para>
  193             <literal>Fixed Width</literal>
  194           </para>
  195         </entry>
  196           </row>
  197           <row rowsep="0">
  198         <entry colname="1" colsep="1" rowsep="1">
  199           <para>
  200             variables
  201           </para>
  202         </entry>
  203         <entry colname="2" rowsep="1">
  204           <para>
  205             <varname>Fixed Width</varname>
  206           </para>
  207         </entry>
  208           </row>
  209           <row rowsep="0">
  210         <entry colname="1" colsep="1">
  211           <para>
  212             Optional input
  213           </para>
  214         </entry>
  215         <entry colname="2">
  216           <para>
  217             <optional>Text is enclosed in square brackets</optional>
  218           </para>
  219         </entry>
  220           </row>
  221         </tbody>
  222       </tgroup>
  223     </informaltable>
  224       </para>
  225     </section>
  226     <section xml:id="dns_overview"><info><title>The Domain Name System (<acronym>DNS</acronym>)</title></info>
  227 
  228       <para>
  229     This document explains the installation
  230     and upkeep of the <acronym>BIND</acronym> (Berkeley Internet
  231     Name Domain) software package. We
  232     begin by reviewing the fundamentals of the Domain Name System
  233     (<acronym>DNS</acronym>) as they relate to <acronym>BIND</acronym>.
  234       </para>
  235 
  236       <section xml:id="dns_fundamentals"><info><title>DNS Fundamentals</title></info>
  237 
  238     <para>
  239       The Domain Name System (DNS) is a hierarchical, distributed
  240       database.  It stores information for mapping Internet host names to
  241       IP
  242       addresses and vice versa, mail routing information, and other data
  243       used by Internet applications.
  244     </para>
  245 
  246     <para>
  247       Clients look up information in the DNS by calling a
  248       <emphasis>resolver</emphasis> library, which sends queries to one or
  249       more <emphasis>name servers</emphasis> and interprets the responses.
  250       The <acronym>BIND</acronym> 9 software distribution
  251       contains a name server, <command>named</command>, and a
  252       resolver library, <command>liblwres</command>.
  253     </para>
  254 
  255     </section>
  256     <section xml:id="domain_names"><info><title>Domains and Domain Names</title></info>
  257 
  258     <para>
  259       The data stored in the DNS is identified by <emphasis>domain names</emphasis> that are organized as a tree according to
  260       organizational or administrative boundaries. Each node of the tree,
  261       called a <emphasis>domain</emphasis>, is given a label. The domain
  262       name of the
  263       node is the concatenation of all the labels on the path from the
  264       node to the <emphasis>root</emphasis> node.  This is represented
  265       in written form as a string of labels listed from right to left and
  266       separated by dots. A label need only be unique within its parent
  267       domain.
  268     </para>
  269 
  270     <para>
  271       For example, a domain name for a host at the
  272       company <emphasis>Example, Inc.</emphasis> could be
  273       <literal>ourhost.example.com</literal>,
  274       where <literal>com</literal> is the
  275       top level domain to which
  276       <literal>ourhost.example.com</literal> belongs,
  277       <literal>example</literal> is
  278       a subdomain of <literal>com</literal>, and
  279       <literal>ourhost</literal> is the
  280       name of the host.
  281     </para>
  282 
  283     <para>
  284       For administrative purposes, the name space is partitioned into
  285       areas called <emphasis>zones</emphasis>, each starting at a node and
  286       extending down to the "leaf" nodes or to nodes where other zones
  287       start.
  288       The data for each zone is stored in a <emphasis>name server</emphasis>, which answers queries about the zone using the
  289       <emphasis>DNS protocol</emphasis>.
  290     </para>
  291 
  292     <para>
  293       The data associated with each domain name is stored in the
  294       form of <emphasis>resource records</emphasis> (<acronym>RR</acronym>s).
  295       Some of the supported resource record types are described in
  296       <xref linkend="types_of_resource_records_and_when_to_use_them"/>.
  297     </para>
  298 
  299     <para>
  300       For more detailed information about the design of the DNS and
  301       the DNS protocol, please refer to the standards documents listed in
  302       <xref linkend="rfcs"/>.
  303     </para>
  304       </section>
  305 
  306       <section xml:id="zones"><info><title>Zones</title></info>
  307 
  308     <para>
  309       To properly operate a name server, it is important to understand
  310       the difference between a <emphasis>zone</emphasis>
  311       and a <emphasis>domain</emphasis>.
  312     </para>
  313 
  314     <para>
  315       As stated previously, a zone is a point of delegation in
  316       the <acronym>DNS</acronym> tree. A zone consists of
  317       those contiguous parts of the domain
  318       tree for which a name server has complete information and over which
  319       it has authority. It contains all domain names from a certain point
  320       downward in the domain tree except those which are delegated to
  321       other zones. A delegation point is marked by one or more
  322       <emphasis>NS records</emphasis> in the
  323       parent zone, which should be matched by equivalent NS records at
  324       the root of the delegated zone.
  325     </para>
  326 
  327     <para>
  328       For instance, consider the <literal>example.com</literal>
  329       domain which includes names
  330       such as <literal>host.aaa.example.com</literal> and
  331       <literal>host.bbb.example.com</literal> even though
  332       the <literal>example.com</literal> zone includes
  333       only delegations for the <literal>aaa.example.com</literal> and
  334       <literal>bbb.example.com</literal> zones.  A zone can
  335       map
  336       exactly to a single domain, but could also include only part of a
  337       domain, the rest of which could be delegated to other
  338       name servers. Every name in the <acronym>DNS</acronym>
  339       tree is a
  340       <emphasis>domain</emphasis>, even if it is
  341       <emphasis>terminal</emphasis>, that is, has no
  342       <emphasis>subdomains</emphasis>.  Every subdomain is a domain and
  343       every domain except the root is also a subdomain. The terminology is
  344       not intuitive and we suggest reading RFCs 1033, 1034, and 1035
  345       to
  346       gain a complete understanding of this difficult and subtle
  347       topic.
  348     </para>
  349 
  350     <para>
  351       Though <acronym>BIND</acronym> is called a "domain name
  352       server",
  353       it deals primarily in terms of zones. The "primary" and "secondary"
  354       declarations in the <filename>named.conf</filename> file
  355       specify
  356       zones, not domains. When BIND asks some other site if it is willing to
  357       be a secondary server for a <emphasis>domain</emphasis>, it is
  358       actually asking for secondary service for some collection of <emphasis>zones</emphasis>.
  359     </para>
  360       </section>
  361 
  362       <section xml:id="auth_servers"><info><title>Authoritative Name Servers</title></info>
  363 
  364     <para>
  365       Each zone is served by at least
  366       one <emphasis>authoritative name server</emphasis>,
  367       which contains the complete data for the zone.
  368       To make the DNS tolerant of server and network failures,
  369       most zones have two or more authoritative servers, on
  370       different networks.
  371     </para>
  372 
  373     <para>
  374       Responses from authoritative servers have the "authoritative
  375       answer" (AA) bit set in the response packets.  This makes them
  376       easy to identify when debugging DNS configurations using tools like
  377       <command>dig</command> (<xref linkend="diagnostic_tools"/>).
  378     </para>
  379 
  380     <section xml:id="primary_master"><info><title>The Primary Server</title></info>
  381 
  382       <para>
  383         The authoritative server where the main copy of the zone
  384         data is maintained is called the
  385         <emphasis>primary</emphasis> (or
  386         <command>master</command>) server, or simply the
  387         <emphasis>primary</emphasis>.  Typically it loads the zone
  388         contents from some local file edited by humans or perhaps
  389         generated mechanically from some other local file which is
  390         edited by humans.  This file is called the
  391         <emphasis>zone file</emphasis> or
  392         <emphasis>master file</emphasis>.
  393       </para>
  394 
  395       <para>
  396         In some cases, however, the zone file may not be edited
  397         by humans at all, but may instead be the result of
  398         <emphasis>dynamic update</emphasis> operations.
  399       </para>
  400     </section>
  401 
  402     <section xml:id="slave_server"><info><title>Secondary Servers</title></info>
  403 
  404       <para>
  405         The other authoritative servers, called the
  406         <emphasis>secondary</emphasis>
  407         (or <command>slave</command>) servers, load the zone
  408         contents from another server using a replication
  409         process known as a <emphasis>zone transfer</emphasis>.
  410         Typically the data is transferred directly from the primary
  411         master, but it is also possible to transfer it from another
  412         secondary.  In other words, a secondary server may itself act as a
  413         primary to a subordinate secondary server.
  414       </para>
  415       <para>
  416         Periodically, the secondary server must send a refresh query to
  417         determine whether the zone contents have been updated. This
  418         is done by sending a query for the zone's Start of Authority (SOA) record and
  419         checking whether the SERIAL field has been updated; if so,
  420         a new transfer request is initiated. The timing of these
  421         refresh queries is controlled by the SOA REFRESH and RETRY
  422         fields, but can be overridden with the
  423         <command>max-refresh-time</command>,
  424         <command>min-refresh-time</command>,
  425         <command>max-retry-time</command>, and
  426         <command>min-retry-time</command> options.
  427       </para>
  428       <para>
  429         If the zone data cannot be updated within the time specified
  430         by the SOA EXPIRE option (up to a hard-coded maximum of
  431         24 weeks), the secondary zone expires and no longer
  432         responds to queries.
  433       </para>
  434     </section>
  435 
  436     <section xml:id="stealth_server"><info><title>Stealth Servers</title></info>
  437 
  438       <para>
  439         Usually, all of the zone's authoritative servers are listed in
  440         NS records in the parent zone.  These NS records constitute
  441         a <emphasis>delegation</emphasis> of the zone from the parent.
  442         The authoritative servers are also listed in the zone file itself,
  443         at the <emphasis>top level</emphasis> or <emphasis>apex</emphasis>
  444         of the zone.  Servers that are not in the parent's NS delegation can be listed in the zone's top-level NS
  445         records, but servers that are not present at
  446         the zone's top level cannot be listed in the parent's delegation.
  447       </para>
  448 
  449       <para>
  450         A <emphasis>stealth server</emphasis> is a server that is
  451         authoritative for a zone but is not listed in that zone's NS
  452         records.  Stealth servers can be used for keeping a local copy of
  453         a
  454         zone, to speed up access to the zone's records, or to make sure that
  455         the
  456         zone is available even if all the "official" servers for the zone
  457         are
  458         inaccessible.
  459       </para>
  460 
  461       <para>
  462         A configuration where the primary server itself is a
  463         stealth server is often referred to as a "hidden primary"
  464         configuration.  One use for this configuration is when the primary
  465         is behind a firewall and is therefore unable to communicate directly
  466         with the outside world.
  467       </para>
  468 
  469     </section>
  470 
  471       </section>
  472       <section xml:id="cache_servers"><info><title>Caching Name Servers</title></info>
  473 
  474     <!--
  475       - Terminology here is inconsistent.  Probably ought to
  476       - convert to using "recursive name server" everywhere
  477       - with just a note about "caching" terminology.
  478       -->
  479 
  480     <para>
  481       The resolver libraries provided by most operating systems are
  482       <emphasis>stub resolvers</emphasis>, meaning that they are not
  483       capable of
  484       performing the full DNS resolution process by themselves by talking
  485       directly to the authoritative servers.  Instead, they rely on a
  486       local
  487       name server to perform the resolution on their behalf.  Such a
  488       server
  489       is called a <emphasis>recursive</emphasis> name server; it performs
  490       <emphasis>recursive lookups</emphasis> for local clients.
  491     </para>
  492 
  493     <para>
  494       To improve performance, recursive servers cache the results of
  495       the lookups they perform.  Since the processes of recursion and
  496       caching are intimately connected, the terms
  497       <emphasis>recursive server</emphasis> and
  498       <emphasis>caching server</emphasis> are often used synonymously.
  499     </para>
  500 
  501     <para>
  502       The length of time for which a record may be retained in
  503       the cache of a caching name server is controlled by the
  504       Time-To-Live (TTL) field associated with each resource record.
  505     </para>
  506 
  507     <section xml:id="forwarder"><info><title>Forwarding</title></info>
  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         Forwarders are typically used when an administrator does not
  520         wish for all the servers at a given site to interact
  521         directly with the rest of the Internet. For example, a
  522         common scenario is when multiple internal DNS servers are
  523         behind an Internet firewall. Servers behind the firewall
  524         forward their requests to the server with external access,
  525         which queries Internet DNS servers on the internal servers'
  526         behalf.
  527       </para>
  528 
  529       <para>
  530         Another scenario (largely now superseded by Response Policy
  531         Zones) is to send queries first to a custom server for RBL
  532         processing before forwarding them to the wider Internet.
  533       </para>
  534 
  535       <para>
  536         There may be one or more forwarders in a given setup. The
  537         order in which the forwarders are listed in
  538         <filename>named.conf</filename> does not determine the
  539         sequence in which they are queried; rather,
  540         <command>named</command> uses the response times from
  541         previous queries to select the server that is likely to
  542         respond the most quickly. A server that has not yet been
  543         queried is given an initial small random response time to
  544         ensure that it is tried at least once. Dynamic adjustment of
  545         the recorded response times ensures that all forwarders are
  546         queried, even those with slower response times.  This
  547         permits changes in behavior based on server responsiveness.
  548       </para>
  549     </section>
  550 
  551       </section>
  552 
  553       <section xml:id="multi_role"><info><title>Name Servers in Multiple Roles</title></info>
  554 
  555     <para>
  556       The <acronym>BIND</acronym> name server can
  557       simultaneously act as
  558       a primary for some zones, a secondary for other zones, and a caching
  559       (recursive) server for a set of local clients.
  560     </para>
  561 
  562     <para>
  563       However, since the functions of authoritative name service
  564       and caching/recursive name service are logically separate, it is
  565       often advantageous to run them on separate server machines.
  566 
  567       A server that only provides authoritative name service
  568       (an <emphasis>authoritative-only</emphasis> server) can run with
  569       recursion disabled, improving reliability and security.
  570 
  571       A server that is not authoritative for any zones and only provides
  572       recursive service to local
  573       clients (a <emphasis>caching-only</emphasis> server)
  574       does not need to be reachable from the Internet at large and can
  575       be placed inside a firewall.
  576     </para>
  577 
  578       </section>
  579     </section>
  580 
  581   </chapter>
  582 
  583   <chapter xml:id="Bv9ARM.ch02"><info><title><acronym>BIND</acronym> Resource Requirements</title></info>
  584 
  585     <section xml:id="hw_req"><info><title>Hardware requirements</title></info>
  586       <para>
  587     <acronym>DNS</acronym> hardware requirements have
  588     traditionally been quite modest.
  589     For many installations, servers that have been retired from
  590     active duty have performed admirably as <acronym>DNS</acronym> servers.
  591       </para>
  592       <para>
  593     However, the DNSSEC features of <acronym>BIND</acronym> 9
  594     may be quite
  595     CPU-intensive, so organizations that make heavy use of these
  596     features may wish to consider larger systems for these applications.
  597     <acronym>BIND</acronym> 9 is fully multithreaded, allowing
  598     full utilization of
  599     multiprocessor systems for installations that need it.
  600       </para>
  601     </section>
  602     <section xml:id="cpu_req"><info><title>CPU Requirements</title></info>
  603       <para>
  604     CPU requirements for <acronym>BIND</acronym> 9 range from
  605     i386-class machines,
  606     for serving static zones without caching, to enterprise-class
  607     machines to process many dynamic updates and DNSSEC-signed zones,
  608     serving many thousands of queries per second.
  609       </para>
  610     </section>
  611     <section xml:id="mem_req"><info><title>Memory Requirements</title></info>
  612       <para>
  613     Server memory must be sufficient to hold both the
  614     cache and the zones loaded from disk.  The <command>max-cache-size</command>
  615     option can limit the amount of memory used by the cache,
  616     at the expense of reducing cache hit rates and causing more <acronym>DNS</acronym>
  617     traffic.
  618     If additional section caching
  619     (<xref linkend="acache"/>) is enabled,
  620     the <command>max-acache-size</command> option can be used to
  621     limit the amount
  622     of memory used by the mechanism.
  623     It is still good practice to have enough memory to load
  624     all zone and cache data into memory; unfortunately, the best
  625     way
  626     to determine this for a given installation is to watch the name server
  627     in operation. After a few weeks, the server process should reach
  628     a relatively stable size where entries are expiring from the cache as
  629     fast as they are being inserted.
  630       </para>
  631       <!--
  632     - Add something here about leaving overhead for attacks?
  633     - How much overhead?  Percentage?
  634     -->
  635     </section>
  636 
  637     <section xml:id="intensive_env"><info><title>Name Server-Intensive Environment Issues</title></info>
  638 
  639       <para>
  640     For name server-intensive environments, there are two
  641     configurations that may be used. The first is one where clients and
  642     any second-level internal name servers query a main name server, which
  643     has enough memory to build a large cache; this approach minimizes
  644     the bandwidth used by external name lookups. The second alternative
  645     is to set up second-level internal name servers to make queries
  646     independently.
  647     In this configuration, none of the individual machines need to
  648     have as much memory or CPU power as in the first alternative, but
  649     this has the disadvantage of making many more external queries,
  650     as none of the name servers share their cached data.
  651       </para>
  652     </section>
  653 
  654     <section xml:id="supported_os"><info><title>Supported Operating Systems</title></info>
  655 
  656       <para>
  657     ISC <acronym>BIND</acronym> 9 compiles and runs on many
  658     Unix-like operating systems and on
  659     Microsoft Windows Server 2012 R2, 2016 and Windows 10.
  660     For an up-to-date
  661     list of supported systems, see the PLATFORMS.md file in the top-level
  662     directory
  663     of the BIND 9 source distribution.
  664       </para>
  665     </section>
  666   </chapter>
  667 
  668   <chapter xml:id="Bv9ARM.ch03"><info><title>Name Server Configuration</title></info>
  669 
  670     <para>
  671       In this chapter we provide some suggested configurations, along
  672       with guidelines for their use.  We suggest reasonable values for
  673       certain option settings.
  674     </para>
  675 
  676     <section xml:id="sample_configuration"><info><title>Sample Configurations</title></info>
  677 
  678       <section xml:id="cache_only_sample"><info><title>A Caching-only Name Server</title></info>
  679 
  680     <para>
  681       The following sample configuration is appropriate for a caching-only
  682       name server for use by clients internal to a corporation.  All
  683       queries
  684       from outside clients are refused using the <command>allow-query</command>
  685       option.  The same effect can be achieved using
  686       suitable
  687       firewall rules.
  688     </para>
  689 
  690 <programlisting>
  691 // Two corporate subnets we wish to allow queries from.
  692 acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
  693 options {
  694      // Working directory
  695      directory "/etc/namedb";
  696 
  697      allow-query { corpnets; };
  698 };
  699 // Provide a reverse mapping for the loopback
  700 // address 127.0.0.1
  701 zone "0.0.127.in-addr.arpa" {
  702      type master;
  703      file "localhost.rev";
  704      notify no;
  705 };
  706 </programlisting>
  707 
  708       </section>
  709 
  710       <section xml:id="auth_only_sample"><info><title>An Authoritative-only Name Server</title></info>
  711 
  712     <para>
  713       This sample configuration is for an authoritative-only server
  714       that is the primary server for "<filename>example.com</filename>"
  715       and a secondary server for the subdomain "<filename>eng.example.com</filename>".
  716     </para>
  717 
  718 <programlisting>
  719 options {
  720      // Working directory
  721      directory "/etc/namedb";
  722      // Do not allow access to cache
  723      allow-query-cache { none; };
  724      // This is the default
  725      allow-query { any; };
  726      // Do not provide recursive service
  727      recursion no;
  728 };
  729 
  730 // Provide a reverse mapping for the loopback
  731 // address 127.0.0.1
  732 zone "0.0.127.in-addr.arpa" {
  733      type master;
  734      file "localhost.rev";
  735      notify no;
  736 };
  737 // We are the primary server for example.com
  738 zone "example.com" {
  739      type master;
  740      file "example.com.db";
  741      // IP addresses of secondary servers allowed to
  742      // transfer example.com
  743      allow-transfer {
  744       192.168.4.14;
  745       192.168.5.53;
  746      };
  747 };
  748 // We are a secondary server for eng.example.com
  749 zone "eng.example.com" {
  750      type slave;
  751      file "eng.example.com.bk";
  752      // IP address of eng.example.com primary server
  753      masters { 192.168.4.12; };
  754 };
  755 </programlisting>
  756 
  757       </section>
  758     </section>
  759 
  760     <section xml:id="load_balancing"><info><title>Load Balancing</title></info>
  761 
  762       <!--
  763     - Add explanation of why load balancing is fragile at best
  764     - and completely pointless in the general case.
  765     -->
  766 
  767       <para>
  768     A primitive form of load balancing can be achieved in
  769     the <acronym>DNS</acronym> by using multiple records
  770     (such as multiple A records) for one name.
  771       </para>
  772 
  773       <para>
  774     For example, assuming three HTTP servers with network addresses
  775     of 10.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the
  776     following means that clients will connect to each machine one-third
  777     of the time:
  778       </para>
  779 
  780       <informaltable colsep="0" rowsep="0">
  781     <tgroup cols="5" colsep="0" rowsep="0" tgroupstyle="2Level-table">
  782       <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/>
  783       <colspec colname="2" colnum="2" colsep="0" colwidth="0.500in"/>
  784       <colspec colname="3" colnum="3" colsep="0" colwidth="0.750in"/>
  785       <colspec colname="4" colnum="4" colsep="0" colwidth="0.750in"/>
  786       <colspec colname="5" colnum="5" colsep="0" colwidth="2.028in"/>
  787       <tbody>
  788         <row rowsep="0">
  789           <entry colname="1">
  790         <para>
  791           Name
  792         </para>
  793           </entry>
  794           <entry colname="2">
  795         <para>
  796           TTL
  797         </para>
  798           </entry>
  799           <entry colname="3">
  800         <para>
  801           CLASS
  802         </para>
  803           </entry>
  804           <entry colname="4">
  805         <para>
  806           TYPE
  807         </para>
  808           </entry>
  809           <entry colname="5">
  810         <para>
  811           Resource Record (RR) Data
  812         </para>
  813           </entry>
  814         </row>
  815         <row rowsep="0">
  816           <entry colname="1">
  817         <para>
  818           <literal>www</literal>
  819         </para>
  820           </entry>
  821           <entry colname="2">
  822         <para>
  823           <literal>600</literal>
  824         </para>
  825           </entry>
  826           <entry colname="3">
  827         <para>
  828           <literal>IN</literal>
  829         </para>
  830           </entry>
  831           <entry colname="4">
  832         <para>
  833           <literal>A</literal>
  834         </para>
  835           </entry>
  836           <entry colname="5">
  837         <para>
  838           <literal>10.0.0.1</literal>
  839         </para>
  840           </entry>
  841         </row>
  842         <row rowsep="0">
  843           <entry colname="1">
  844         <para/>
  845           </entry>
  846           <entry colname="2">
  847         <para>
  848           <literal>600</literal>
  849         </para>
  850           </entry>
  851           <entry colname="3">
  852         <para>
  853           <literal>IN</literal>
  854         </para>
  855           </entry>
  856           <entry colname="4">
  857         <para>
  858           <literal>A</literal>
  859         </para>
  860           </entry>
  861           <entry colname="5">
  862         <para>
  863           <literal>10.0.0.2</literal>
  864         </para>
  865           </entry>
  866         </row>
  867         <row rowsep="0">
  868           <entry colname="1">
  869         <para/>
  870           </entry>
  871           <entry colname="2">
  872         <para>
  873           <literal>600</literal>
  874         </para>
  875           </entry>
  876           <entry colname="3">
  877         <para>
  878           <literal>IN</literal>
  879         </para>
  880           </entry>
  881           <entry colname="4">
  882         <para>
  883           <literal>A</literal>
  884         </para>
  885           </entry>
  886           <entry colname="5">
  887         <para>
  888           <literal>10.0.0.3</literal>
  889         </para>
  890           </entry>
  891         </row>
  892       </tbody>
  893     </tgroup>
  894       </informaltable>
  895       <para>
  896     When a resolver queries for these records, <acronym>BIND</acronym> rotates
  897     them and responds to the query with the records in a different
  898     order.  In the example above, clients randomly receive
  899     records in the order 1, 2, 3; 2, 3, 1; and 3, 1, 2. Most clients
  900     use the first record returned and discard the rest.
  901       </para>
  902       <para>
  903     For more detail on ordering responses, check the
  904     <command>rrset-order</command> sub-statement in the
  905     <command>options</command> statement, see
  906     <xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>.
  907       </para>
  908 
  909     </section>
  910 
  911     <section xml:id="ns_operations"><info><title>Name Server Operations</title></info>
  912 
  913       <section xml:id="tools"><info><title>Tools for Use With the Name Server Daemon</title></info>
  914     <para>
  915       This section describes several indispensable diagnostic,
  916       administrative, and monitoring tools available to the system
  917       administrator for controlling and debugging the name server
  918       daemon.
  919     </para>
  920     <section xml:id="diagnostic_tools"><info><title>Diagnostic Tools</title></info>
  921       <para>
  922         The <command>dig</command>, <command>host</command>, and
  923         <command>nslookup</command> programs are all command-line tools
  924         for manually querying name servers.  They differ in style and
  925         output format.
  926       </para>
  927 
  928       <variablelist>
  929         <varlistentry>
  930           <term xml:id="dig"><command>dig</command></term>
  931           <listitem>
  932         <para>
  933           <command>dig</command>
  934           is the most versatile and complete of these lookup tools.
  935           It has two modes: simple interactive
  936           mode for a single query, and batch mode, which executes a
  937           query for
  938           each in a list of several query lines. All query options are
  939           accessible
  940           from the command line.
  941         </para>
  942         <cmdsynopsis label="Usage" sepchar=" ">
  943           <command>dig</command>
  944           <arg choice="opt" rep="norepeat">@<replaceable>server</replaceable></arg>
  945           <arg choice="plain" rep="norepeat"><replaceable>domain</replaceable></arg>
  946           <arg choice="opt" rep="norepeat"><replaceable>query-type</replaceable></arg>
  947           <arg choice="opt" rep="norepeat"><replaceable>query-class</replaceable></arg>
  948           <arg choice="opt" rep="norepeat">+<replaceable>query-option</replaceable></arg>
  949           <arg choice="opt" rep="norepeat">-<replaceable>dig-option</replaceable></arg>
  950           <arg choice="opt" rep="norepeat">%<replaceable>comment</replaceable></arg>
  951         </cmdsynopsis>
  952         <para>
  953           The usual simple use of <command>dig</command> takes the form
  954         </para>
  955         <simpara>
  956           <command>dig @server domain query-type query-class</command>
  957         </simpara>
  958         <para>
  959           For more information and a list of available commands and
  960           options, see the <command>dig</command> man
  961           page.
  962         </para>
  963           </listitem>
  964         </varlistentry>
  965 
  966         <varlistentry>
  967           <term><command>host</command></term>
  968           <listitem>
  969         <para>
  970           The <command>host</command> utility emphasizes
  971           simplicity
  972           and ease of use.  By default, it converts
  973           between host names and Internet addresses, but its
  974           functionality
  975           can be extended with the use of options.
  976         </para>
  977         <cmdsynopsis label="Usage" sepchar=" ">
  978           <command>host</command>
  979           <arg choice="opt" rep="norepeat">-aCdlnrsTwv</arg>
  980           <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg>
  981           <arg choice="opt" rep="norepeat">-N <replaceable>ndots</replaceable></arg>
  982           <arg choice="opt" rep="norepeat">-t <replaceable>type</replaceable></arg>
  983           <arg choice="opt" rep="norepeat">-W <replaceable>timeout</replaceable></arg>
  984           <arg choice="opt" rep="norepeat">-R <replaceable>retries</replaceable></arg>
  985           <arg choice="opt" rep="norepeat">-m <replaceable>flag</replaceable></arg>
  986           <arg choice="opt" rep="norepeat">-4</arg>
  987           <arg choice="opt" rep="norepeat">-6</arg>
  988           <arg choice="plain" rep="norepeat"><replaceable>hostname</replaceable></arg>
  989           <arg choice="opt" rep="norepeat"><replaceable>server</replaceable></arg>
  990         </cmdsynopsis>
  991         <para>
  992           For more information and a list of available commands and
  993           options, see the <command>host</command> man
  994           page.
  995         </para>
  996           </listitem>
  997         </varlistentry>
  998 
  999         <varlistentry>
 1000           <term><command>nslookup</command></term>
 1001           <listitem>
 1002         <para><command>nslookup</command>
 1003           has two modes: interactive and
 1004           non-interactive. Interactive mode allows the user to
 1005           query name servers for information about various
 1006           hosts and domains, or to print a list of hosts in a
 1007           domain. Non-interactive mode is used to print just
 1008           the name and requested information for a host or
 1009           domain.
 1010         </para>
 1011         <cmdsynopsis label="Usage" sepchar=" ">
 1012           <command>nslookup</command>
 1013           <arg rep="repeat" choice="opt">-option</arg>
 1014           <group choice="opt" rep="norepeat">
 1015             <arg choice="opt" rep="norepeat"><replaceable>host-to-find</replaceable></arg>
 1016             <arg choice="opt" rep="norepeat">- <arg choice="opt" rep="norepeat">server</arg></arg>
 1017           </group>
 1018         </cmdsynopsis>
 1019         <para>
 1020           Interactive mode is entered when no arguments are given (the
 1021           default name server is used) or when the first argument
 1022           is a
 1023           hyphen ("-") and the second argument is the host name or
 1024           Internet address
 1025           of a name server.
 1026         </para>
 1027         <para>
 1028           Non-interactive mode is used when the name or Internet
 1029           address
 1030           of the host to be looked up is given as the first argument.
 1031           The
 1032           optional second argument specifies the host name or address
 1033           of a name server.
 1034         </para>
 1035         <para>
 1036           Due to its arcane user interface and frequently inconsistent
 1037           behavior, we do not recommend the use of <command>nslookup</command>.
 1038           Use <command>dig</command> instead.
 1039         </para>
 1040           </listitem>
 1041 
 1042         </varlistentry>
 1043       </variablelist>
 1044     </section>
 1045 
 1046     <section xml:id="admin_tools"><info><title>Administrative Tools</title></info>
 1047       <para>
 1048         Administrative tools play an integral part in the management
 1049         of a server.
 1050       </para>
 1051       <variablelist>
 1052         <varlistentry xml:id="named-checkconf" xreflabel="Named Configuration Checking application">
 1053 
 1054           <term><command>named-checkconf</command></term>
 1055           <listitem>
 1056         <para>
 1057           The <command>named-checkconf</command> program
 1058           checks the syntax of a <filename>named.conf</filename> file.
 1059         </para>
 1060         <cmdsynopsis label="Usage" sepchar=" ">
 1061           <command>named-checkconf</command>
 1062           <arg choice="opt" rep="norepeat">-jvz</arg>
 1063           <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg>
 1064           <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg>
 1065         </cmdsynopsis>
 1066           </listitem>
 1067         </varlistentry>
 1068         <varlistentry xml:id="named-checkzone" xreflabel="Zone Checking application">
 1069 
 1070           <term><command>named-checkzone</command></term>
 1071           <listitem>
 1072         <para>
 1073           The <command>named-checkzone</command> program
 1074           checks a zone file for
 1075           syntax and consistency.
 1076         </para>
 1077         <cmdsynopsis label="Usage" sepchar=" ">
 1078           <command>named-checkzone</command>
 1079           <arg choice="opt" rep="norepeat">-djqvD</arg>
 1080           <arg choice="opt" rep="norepeat">-c <replaceable>class</replaceable></arg>
 1081           <arg choice="opt" rep="norepeat">-o <replaceable>output</replaceable></arg>
 1082           <arg choice="opt" rep="norepeat">-t <replaceable>directory</replaceable></arg>
 1083           <arg choice="opt" rep="norepeat">-w <replaceable>directory</replaceable></arg>
 1084           <arg choice="opt" rep="norepeat">-k <replaceable>(ignore|warn|fail)</replaceable></arg>
 1085           <arg choice="opt" rep="norepeat">-n <replaceable>(ignore|warn|fail)</replaceable></arg>
 1086           <arg choice="opt" rep="norepeat">-W <replaceable>(ignore|warn)</replaceable></arg>
 1087           <arg choice="plain" rep="norepeat"><replaceable>zone</replaceable></arg>
 1088           <arg choice="opt" rep="norepeat"><replaceable>filename</replaceable></arg>
 1089         </cmdsynopsis>
 1090           </listitem>
 1091         </varlistentry>
 1092         <varlistentry xml:id="named-compilezone" xreflabel="Zone Compilation application">
 1093           <term><command>named-compilezone</command></term>
 1094           <listitem>
 1095         <para>
 1096           This tool is similar to <command>named-checkzone,</command> but
 1097           it always dumps the zone content to a specified file
 1098           (typically in a different format).
 1099         </para>
 1100           </listitem>
 1101         </varlistentry>
 1102         <varlistentry xml:id="rndc" xreflabel="Remote Name Daemon Control application">
 1103 
 1104           <term><command>rndc</command></term>
 1105           <listitem>
 1106         <para>
 1107           The remote name daemon control
 1108           (<command>rndc</command>) program allows the
 1109           system
 1110           administrator to control the operation of a name server.
 1111           If <command>rndc</command> is run without any
 1112           options,
 1113           it displays a usage message as follows:
 1114         </para>
 1115         <cmdsynopsis label="Usage" sepchar=" ">
 1116           <command>rndc</command>
 1117           <arg choice="opt" rep="norepeat">-c <replaceable>config</replaceable></arg>
 1118           <arg choice="opt" rep="norepeat">-s <replaceable>server</replaceable></arg>
 1119           <arg choice="opt" rep="norepeat">-p <replaceable>port</replaceable></arg>
 1120           <arg choice="opt" rep="norepeat">-y <replaceable>key</replaceable></arg>
 1121           <arg choice="plain" rep="norepeat"><replaceable>command</replaceable></arg>
 1122           <arg rep="repeat" choice="opt"><replaceable>command</replaceable></arg>
 1123         </cmdsynopsis>
 1124 
 1125         <para>See <xref linkend="man.rndc"/> for details of
 1126           the available <command>rndc</command> commands.
 1127         </para>
 1128 
 1129         <para>
 1130           <command>rndc</command> requires a configuration file,
 1131           since all
 1132           communication with the server is authenticated with
 1133           digital signatures that rely on a shared secret, and
 1134           there is no way to provide that secret other than with a
 1135           configuration file.  The default location for the
 1136           <command>rndc</command> configuration file is
 1137           <filename>/etc/rndc.conf</filename>, but an
 1138           alternate
 1139           location can be specified with the <option>-c</option>
 1140           option.  If the configuration file is not found,
 1141           <command>rndc</command> also looks in
 1142           <filename>/etc/rndc.key</filename> (or whatever
 1143           <varname>sysconfdir</varname> was defined when
 1144           the <acronym>BIND</acronym> build was
 1145           configured).
 1146           The <filename>rndc.key</filename> file is
 1147           generated by
 1148           running <command>rndc-confgen -a</command> as
 1149           described in
 1150           <xref linkend="controls_statement_definition_and_usage"/>.
 1151         </para>
 1152 
 1153         <para>
 1154           The format of the configuration file is similar to
 1155           that of <filename>named.conf</filename>, but is
 1156           limited to
 1157           only four statements: the <command>options</command>,
 1158           <command>key</command>, <command>server</command>, and
 1159           <command>include</command>
 1160           statements.  These statements are what associate the
 1161           secret keys to the servers with which they are meant to
 1162           be shared.  The order of statements is not
 1163           significant.
 1164         </para>
 1165 
 1166         <para>
 1167           The <command>options</command> statement has
 1168           three clauses:
 1169           <command>default-server</command>, <command>default-key</command>,
 1170           and <command>default-port</command>.
 1171           <command>default-server</command> takes a
 1172           host name or address argument and represents the server
 1173           that
 1174           is contacted if no <option>-s</option>
 1175           option is provided on the command line.
 1176           <command>default-key</command> takes
 1177           the name of a key as its argument, as defined by a <command>key</command> statement.
 1178           <command>default-port</command> specifies the
 1179           port to which
 1180           <command>rndc</command> should connect if no
 1181           port is given on the command line or in a
 1182           <command>server</command> statement.
 1183         </para>
 1184 
 1185         <para>
 1186           The <command>key</command> statement defines a
 1187           key to be used
 1188           by <command>rndc</command> when authenticating
 1189           with
 1190           <command>named</command>.  Its syntax is
 1191           identical to the
 1192           <command>key</command> statement in <filename>named.conf</filename>.
 1193           The keyword <userinput>key</userinput> is
 1194           followed by a key name, which must be a valid
 1195           domain name, though it need not actually be hierarchical;
 1196           thus,
 1197           a string like "<userinput>rndc_key</userinput>" is a valid
 1198           name.
 1199           The <command>key</command> statement has two
 1200           clauses:
 1201           <command>algorithm</command> and <command>secret</command>.
 1202           While the configuration parser accepts any string as the
 1203           argument
 1204           to <command>algorithm</command>, currently only the strings
 1205           "<userinput>hmac-md5</userinput>",
 1206           "<userinput>hmac-sha1</userinput>",
 1207           "<userinput>hmac-sha224</userinput>",
 1208           "<userinput>hmac-sha256</userinput>",
 1209           "<userinput>hmac-sha384</userinput>",
 1210           and "<userinput>hmac-sha512</userinput>"
 1211           have any meaning.  The secret is a Base64-encoded string
 1212           as specified in RFC 3548.
 1213         </para>
 1214 
 1215         <para>
 1216           The <command>server</command> statement
 1217           associates a key
 1218           defined using the <command>key</command>
 1219           statement with a server.
 1220           The keyword <userinput>server</userinput> is followed by a
 1221           host name or address.  The <command>server</command> statement
 1222           has two clauses: <command>key</command> and <command>port</command>.
 1223           The <command>key</command> clause specifies the
 1224           name of the key
 1225           to be used when communicating with this server, and the
 1226           <command>port</command> clause can be used to
 1227           specify the port <command>rndc</command> should
 1228           connect
 1229           to on the server.
 1230         </para>
 1231 
 1232         <para>
 1233           A sample minimal configuration file is as follows:
 1234         </para>
 1235 
 1236 <programlisting>
 1237 key rndc_key {
 1238      algorithm "hmac-sha256";
 1239      secret
 1240        "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
 1241 };
 1242 options {
 1243      default-server 127.0.0.1;
 1244      default-key    rndc_key;
 1245 };
 1246 </programlisting>
 1247 
 1248         <para>
 1249           This file, if installed as <filename>/etc/rndc.conf</filename>,
 1250           allows the command:
 1251         </para>
 1252 
 1253         <para>
 1254           <prompt>$ </prompt><userinput>rndc reload</userinput>
 1255         </para>
 1256 
 1257         <para>
 1258           to connect to 127.0.0.1 port 953 and causes the name server
 1259           to reload, if a name server on the local machine is
 1260           running with
 1261           following controls statements:
 1262         </para>
 1263 
 1264 <programlisting>
 1265 controls {
 1266     inet 127.0.0.1
 1267         allow { localhost; } keys { rndc_key; };
 1268 };
 1269 </programlisting>
 1270 
 1271         <para>
 1272           and it has an identical key statement for
 1273           <literal>rndc_key</literal>.
 1274         </para>
 1275 
 1276         <para>
 1277           Running the <command>rndc-confgen</command>
 1278           program
 1279           conveniently creates an <filename>rndc.conf</filename>
 1280           file, and also displays the
 1281           corresponding <command>controls</command>
 1282           statement needed to
 1283           add to <filename>named.conf</filename>.
 1284           Alternatively,
 1285           it is possible to run <command>rndc-confgen -a</command>
 1286           to set up
 1287           an <filename>rndc.key</filename> file and not
 1288           modify
 1289           <filename>named.conf</filename> at all.
 1290         </para>
 1291 
 1292           </listitem>
 1293         </varlistentry>
 1294       </variablelist>
 1295 
 1296     </section>
 1297       </section>
 1298 
 1299       <section xml:id="signals"><info><title>Signals</title></info>
 1300     <para>
 1301       Certain Unix signals cause the name server to take specific
 1302       actions, as described in the following table.  These signals can
 1303       be sent using the <command>kill</command> command.
 1304     </para>
 1305     <informaltable frame="all">
 1306       <tgroup cols="2">
 1307         <colspec colname="1" colnum="1" colsep="0" colwidth="1.125in"/>
 1308         <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/>
 1309         <tbody>
 1310           <row rowsep="0">
 1311         <entry colname="1">
 1312           <para><command>SIGHUP</command></para>
 1313         </entry>
 1314         <entry colname="2">
 1315           <para>
 1316             Causes the server to read <filename>named.conf</filename> and
 1317             reload the database.
 1318           </para>
 1319         </entry>
 1320           </row>
 1321           <row rowsep="0">
 1322         <entry colname="1">
 1323           <para><command>SIGTERM</command></para>
 1324         </entry>
 1325         <entry colname="2">
 1326           <para>
 1327             Causes the server to clean up and exit.
 1328           </para>
 1329         </entry>
 1330           </row>
 1331           <row rowsep="0">
 1332         <entry colname="1">
 1333           <para><command>SIGINT</command></para>
 1334         </entry>
 1335         <entry colname="2">
 1336           <para>
 1337             Causes the server to clean up and exit.
 1338           </para>
 1339         </entry>
 1340           </row>
 1341         </tbody>
 1342       </tgroup>
 1343     </informaltable>
 1344       </section>
 1345     </section>
 1346   </chapter>
 1347 
 1348   <chapter xml:id="Bv9ARM.ch04"><info><title>Advanced DNS Features</title></info>
 1349 
 1350     <section xml:id="notify"><info><title>Notify</title></info>
 1351       <para>
 1352     <acronym>DNS</acronym> NOTIFY is a mechanism that allows primary
 1353     servers to notify their secondary servers of changes to a zone's data. In
 1354     response to a <command>NOTIFY</command> from a primary server, the
 1355     secondary checks to see that its version of the zone is the
 1356     current version and, if not, initiates a zone transfer.
 1357       </para>
 1358 
 1359       <para>
 1360     For more information about <acronym>DNS</acronym>
 1361     <command>NOTIFY</command>, see the description of the
 1362     <command>notify</command> option in <xref linkend="boolean_options"/> and
 1363     the description of the zone option <command>also-notify</command> in
 1364     <xref linkend="zone_transfers"/>.  The <command>NOTIFY</command>
 1365     protocol is specified in RFC 1996.
 1366       </para>
 1367 
 1368       <note><simpara>
 1369     As a secondary zone can also be a primary to other secondaries, <command>named</command>,
 1370     by default, sends <command>NOTIFY</command> messages for every zone
 1371     it loads.  Specifying <command>notify primary-only;</command>
 1372     causes <command>named</command> to only send <command>NOTIFY</command> for primary
 1373     zones that it loads.
 1374       </simpara></note>
 1375 
 1376     </section>
 1377 
 1378     <section xml:id="dynamic_update"><info><title>Dynamic Update</title></info>
 1379 
 1380       <para>
 1381     Dynamic Update is a method for adding, replacing, or deleting
 1382     records in a primary server by sending it a special form of DNS
 1383     messages.  The format and meaning of these messages is specified
 1384     in RFC 2136.
 1385       </para>
 1386 
 1387       <para>
 1388     Dynamic update is enabled by including an
 1389     <command>allow-update</command> or an <command>update-policy</command>
 1390     clause in the <command>zone</command> statement.
 1391       </para>
 1392 
 1393       <para>
 1394     If the zone's <command>update-policy</command> is set to
 1395     <userinput>local</userinput>, updates to the zone
 1396     are permitted for the key <varname>local-ddns</varname>,
 1397     which is generated by <command>named</command> at startup.
 1398     See <xref linkend="dynamic_update_policies"/> for more details.
 1399       </para>
 1400 
 1401       <para>
 1402     Dynamic updates using Kerberos-signed requests can be made
 1403     using the TKEY/GSS protocol, either by setting the
 1404     <command>tkey-gssapi-keytab</command> option, or
 1405     by setting both the <command>tkey-gssapi-credential</command>
 1406     and <command>tkey-domain</command> options. Once enabled,
 1407     Kerberos-signed requests are matched against the update
 1408     policies for the zone, using the Kerberos principal as the
 1409     signer for the request.
 1410       </para>
 1411 
 1412       <para>
 1413     Updating of secure zones (zones using DNSSEC) follows RFC
 1414     3007: RRSIG, NSEC, and NSEC3 records affected by updates are
 1415     automatically regenerated by the server using an online
 1416     zone key.  Update authorization is based on transaction
 1417     signatures and an explicit server policy.
 1418       </para>
 1419 
 1420       <section xml:id="journal"><info><title>The Journal File</title></info>
 1421 
 1422     <para>
 1423       All changes made to a zone using dynamic update are stored
 1424       in the zone's journal file.  This file is automatically created
 1425       by the server when the first dynamic update takes place.
 1426       The name of the journal file is formed by appending the extension
 1427       <filename>.jnl</filename> to the name of the
 1428       corresponding zone
 1429       file, unless specifically overridden.  The journal file is in a
 1430       binary format and should not be edited manually.
 1431     </para>
 1432 
 1433     <para>
 1434       The server also occasionally writes ("dumps")
 1435       the complete contents of the updated zone to its zone file.
 1436       This is not done immediately after
 1437       each dynamic update, because that would be too slow when a large
 1438       zone is updated frequently.  Instead, the dump is delayed by
 1439       up to 15 minutes, allowing additional updates to take place.
 1440       During the dump process, transient files are created
 1441       with the extensions <filename>.jnw</filename> and
 1442       <filename>.jbk</filename>; under ordinary circumstances, these
 1443       are removed when the dump is complete, and can be safely
 1444       ignored.
 1445     </para>
 1446 
 1447     <para>
 1448       When a server is restarted after a shutdown or crash, it replays
 1449       the journal file to incorporate into the zone any updates that
 1450       took
 1451       place after the last zone dump.
 1452     </para>
 1453 
 1454     <para>
 1455       Changes that result from incoming incremental zone transfers are
 1456       also
 1457       journaled in a similar way.
 1458     </para>
 1459 
 1460     <para>
 1461       The zone files of dynamic zones cannot normally be edited by
 1462       hand because they are not guaranteed to contain the most recent
 1463       dynamic changes; those are only in the journal file.
 1464       The only way to ensure that the zone file of a dynamic zone
 1465       is up-to-date is to run <command>rndc stop</command>.
 1466     </para>
 1467 
 1468     <para>
 1469       To make changes to a dynamic zone
 1470       manually, follow these steps:
 1471       first, disable dynamic updates to the zone using
 1472       <command>rndc freeze <replaceable>zone</replaceable></command>.
 1473       This updates the zone file with the changes
 1474       stored in its <filename>.jnl</filename> file.
 1475       Then, edit the zone file.  Finally, run
 1476       <command>rndc thaw <replaceable>zone</replaceable></command>
 1477       to reload the changed zone and re-enable dynamic updates.
 1478     </para>
 1479 
 1480     <para>
 1481       <command>rndc sync <replaceable>zone</replaceable></command>
 1482       updates the zone file with changes from the journal file
 1483       without stopping dynamic updates; this may be useful for viewing
 1484       the current zone state.  To remove the <filename>.jnl</filename>
 1485       file after updating the zone file, use
 1486       <command>rndc sync -clean</command>.
 1487     </para>
 1488 
 1489       </section>
 1490 
 1491     </section>
 1492 
 1493     <section xml:id="incremental_zone_transfers"><info><title>Incremental Zone Transfers (IXFR)</title></info>
 1494 
 1495       <para>
 1496     The incremental zone transfer (IXFR) protocol is a way for
 1497     secondary servers to transfer only changed data, instead of having to
 1498     transfer an entire zone. The IXFR protocol is specified in RFC
 1499     1995. See <xref linkend="proposed_standards"/>.
 1500       </para>
 1501 
 1502       <para>
 1503     When acting as a primary server, <acronym>BIND</acronym> 9
 1504     supports IXFR for those zones
 1505     where the necessary change history information is available. These
 1506     include primary zones maintained by dynamic update and secondary zones
 1507     whose data was obtained by IXFR.  For manually maintained primary
 1508     zones, and for secondary zones obtained by performing a full zone
 1509     transfer (AXFR), IXFR is supported only if the option
 1510     <command>ixfr-from-differences</command> is set
 1511     to <userinput>yes</userinput>.
 1512       </para>
 1513 
 1514       <para>
 1515     When acting as a secondary server, <acronym>BIND</acronym> 9
 1516     attempts to use IXFR unless
 1517     it is explicitly disabled. For more information about disabling
 1518     IXFR, see the description of the <command>request-ixfr</command> clause
 1519     of the <command>server</command> statement.
 1520       </para>
 1521     </section>
 1522 
 1523     <section xml:id="split_dns"><info><title>Split DNS</title></info>
 1524 
 1525       <para>
 1526     Setting up different views of the DNS space to
 1527     internal and external resolvers is usually referred to as a
 1528     <emphasis>split DNS</emphasis> setup. There are several
 1529     reasons an organization might want to set up its DNS this way.
 1530       </para>
 1531       <para>
 1532     One common reason to use split DNS is
 1533     to hide "internal" DNS information from "external" clients on the
 1534     Internet. There is some debate as to whether this is actually
 1535     useful.
 1536     Internal DNS information leaks out in many ways (via email headers,
 1537     for example) and most savvy "attackers" can find the information
 1538     they need using other means.
 1539     However, since listing addresses of internal servers that
 1540     external clients cannot possibly reach can result in
 1541     connection delays and other annoyances, an organization may
 1542     choose to use split DNS to present a consistent view of itself
 1543     to the outside world.
 1544       </para>
 1545       <para>
 1546     Another common reason for setting up a split DNS system is
 1547     to allow internal networks that are behind filters or in RFC 1918
 1548     space (reserved IP space, as documented in RFC 1918) to resolve DNS
 1549     on the Internet. Split DNS can also be used to allow mail from outside
 1550     back into the internal network.
 1551       </para>
 1552       <section xml:id="split_dns_sample"><info><title>Example Split DNS Setup</title></info>
 1553     <para>
 1554       Let's say a company named <emphasis>Example, Inc.</emphasis>
 1555       (<literal>example.com</literal>)
 1556       has several corporate sites that have an internal network with
 1557       reserved
 1558       Internet Protocol (IP) space and an external demilitarized zone (DMZ),
 1559       or "outside" section of a network, that is available to the public.
 1560     </para>
 1561     <para>
 1562       <emphasis>Example, Inc.</emphasis> wants its internal clients
 1563       to be able to resolve external hostnames and to exchange mail with
 1564       people on the outside. The company also wants its internal resolvers
 1565       to have access to certain internal-only zones that are not available
 1566       at all outside of the internal network.
 1567     </para>
 1568     <para>
 1569       In order to accomplish this, the company sets up two sets
 1570       of name servers. One set is on the inside network (in the
 1571       reserved
 1572       IP space) and the other set is on bastion hosts, which are
 1573       "proxy"
 1574       hosts in the DMZ that can talk to both sides of its network.
 1575     </para>
 1576     <para>
 1577       The internal servers are configured to forward all queries,
 1578       except queries for <filename>site1.internal</filename>, <filename>site2.internal</filename>, <filename>site1.example.com</filename>,
 1579       and <filename>site2.example.com</filename>, to the servers
 1580       in the
 1581       DMZ. These internal servers will have complete sets of information
 1582       for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>, <filename>site1.internal</filename>,
 1583       and <filename>site2.internal</filename>.
 1584     </para>
 1585     <para>
 1586       To protect the <filename>site1.internal</filename> and <filename>site2.internal</filename> domains,
 1587       the internal name servers must be configured to disallow all queries
 1588       to these domains from any external hosts, including the bastion
 1589       hosts.
 1590     </para>
 1591     <para>
 1592       The external servers, which are on the bastion hosts, are
 1593       configured to serve the "public" version of the <filename>site1.example.com</filename> and <filename>site2.example.com</filename> zones.
 1594       This could include things such as the host records for public servers
 1595       (<filename>www.example.com</filename> and <filename>ftp.example.com</filename>)
 1596       and mail exchange (MX) records (<filename>a.mx.example.com</filename> and <filename>b.mx.example.com</filename>).
 1597     </para>
 1598     <para>
 1599       In addition, the public <filename>site1.example.com</filename> and <filename>site2.example.com</filename> zones
 1600       should have special MX records that contain wildcard ("*") records
 1601       pointing to the bastion hosts. This is needed because external mail
 1602       servers do not have any other way of looking up how to deliver mail
 1603       to those internal hosts. With the wildcard records, the mail is
 1604       delivered to the bastion host, which can then forward it on to
 1605       internal hosts.
 1606     </para>
 1607     <para>
 1608       Here's an example of a wildcard MX record:
 1609     </para>
 1610     <programlisting>*   IN MX 10 external1.example.com.</programlisting>
 1611     <para>
 1612       Now that they accept mail on behalf of anything in the internal
 1613       network, the bastion hosts need to know how to deliver mail
 1614       to internal hosts. The resolvers
 1615       on
 1616       the bastion hosts need to be configured to point to the internal
 1617       name servers for DNS resolution.
 1618     </para>
 1619     <para>
 1620       Queries for internal hostnames are answered by the internal
 1621       servers, and queries for external hostnames are forwarded back
 1622       out to the DNS servers on the bastion hosts.
 1623     </para>
 1624     <para>
 1625       For all of this to work properly, internal clients
 1626       need to be configured to query <emphasis>only</emphasis> the internal
 1627       name servers for DNS queries. This could also be enforced via
 1628       selective
 1629       filtering on the network.
 1630     </para>
 1631     <para>
 1632       If everything has been set properly, <emphasis>Example, Inc.</emphasis>'s
 1633       internal clients are now able to:
 1634     </para>
 1635     <itemizedlist>
 1636       <listitem>
 1637         <simpara>
 1638           Look up any hostnames in the <literal>site1.example.com</literal>
 1639           and
 1640           <literal>site2.example.com</literal> zones.
 1641         </simpara>
 1642       </listitem>
 1643       <listitem>
 1644         <simpara>
 1645           Look up any hostnames in the <literal>site1.internal</literal> and
 1646           <literal>site2.internal</literal> domains.
 1647         </simpara>
 1648       </listitem>
 1649       <listitem>
 1650         <simpara>Look up any hostnames on the Internet.</simpara>
 1651       </listitem>
 1652       <listitem>
 1653         <simpara>Exchange mail with both internal and external users.</simpara>
 1654       </listitem>
 1655     </itemizedlist>
 1656     <para>
 1657       Hosts on the Internet are able to:
 1658     </para>
 1659     <itemizedlist>
 1660       <listitem>
 1661         <simpara>
 1662           Look up any hostnames in the <literal>site1.example.com</literal>
 1663           and
 1664           <literal>site2.example.com</literal> zones.
 1665         </simpara>
 1666       </listitem>
 1667       <listitem>
 1668         <simpara>
 1669           Exchange mail with anyone in the <literal>site1.example.com</literal> and
 1670           <literal>site2.example.com</literal> zones.
 1671         </simpara>
 1672       </listitem>
 1673     </itemizedlist>
 1674 
 1675     <para>
 1676       Here is an example configuration for the setup just
 1677       described above. Note that this is only configuration information;
 1678       for information on how to configure the zone files, see <xref linkend="sample_configuration"/>.
 1679     </para>
 1680 
 1681     <para>
 1682       Internal DNS server config:
 1683     </para>
 1684 
 1685 <programlisting>
 1686 
 1687 acl internals { 172.16.72.0/24; 192.168.1.0/24; };
 1688 
 1689 acl externals { <varname>bastion-ips-go-here</varname>; };
 1690 
 1691 options {
 1692     ...
 1693     ...
 1694     forward only;
 1695     // forward to external servers
 1696     forwarders {
 1697     <varname>bastion-ips-go-here</varname>;
 1698     };
 1699     // sample allow-transfer (no one)
 1700     allow-transfer { none; };
 1701     // restrict query access
 1702     allow-query { internals; externals; };
 1703     // restrict recursion
 1704     allow-recursion { internals; };
 1705     ...
 1706     ...
 1707 };
 1708 
 1709 // sample primary zone
 1710 zone "site1.example.com" {
 1711   type master;
 1712   file "m/site1.example.com";
 1713   // do normal iterative resolution (do not forward)
 1714   forwarders { };
 1715   allow-query { internals; externals; };
 1716   allow-transfer { internals; };
 1717 };
 1718 
 1719 // sample secondary zone
 1720 zone "site2.example.com" {
 1721   type slave;
 1722   file "s/site2.example.com";
 1723   masters { 172.16.72.3; };
 1724   forwarders { };
 1725   allow-query { internals; externals; };
 1726   allow-transfer { internals; };
 1727 };
 1728 
 1729 zone "site1.internal" {
 1730   type master;
 1731   file "m/site1.internal";
 1732   forwarders { };
 1733   allow-query { internals; };
 1734   allow-transfer { internals; }
 1735 };
 1736 
 1737 zone "site2.internal" {
 1738   type slave;
 1739   file "s/site2.internal";
 1740   masters { 172.16.72.3; };
 1741   forwarders { };
 1742   allow-query { internals };
 1743   allow-transfer { internals; }
 1744 };
 1745 </programlisting>
 1746 
 1747     <para>
 1748       External (bastion host) DNS server config:
 1749     </para>
 1750 
 1751 <programlisting>
 1752 acl internals { 172.16.72.0/24; 192.168.1.0/24; };
 1753 
 1754 acl externals { bastion-ips-go-here; };
 1755 
 1756 options {
 1757   ...
 1758   ...
 1759   // sample allow-transfer (no one)
 1760   allow-transfer { none; };
 1761   // default query access
 1762   allow-query { any; };
 1763   // restrict cache access
 1764   allow-query-cache { internals; externals; };
 1765   // restrict recursion
 1766   allow-recursion { internals; externals; };
 1767   ...
 1768   ...
 1769 };
 1770 
 1771 // sample secondary zone
 1772 zone "site1.example.com" {
 1773   type master;
 1774   file "m/site1.foo.com";
 1775   allow-transfer { internals; externals; };
 1776 };
 1777 
 1778 zone "site2.example.com" {
 1779   type slave;
 1780   file "s/site2.foo.com";
 1781   masters { another_bastion_host_maybe; };
 1782   allow-transfer { internals; externals; }
 1783 };
 1784 </programlisting>
 1785 
 1786     <para>
 1787       In the <filename>resolv.conf</filename> (or equivalent) on
 1788       the bastion host(s):
 1789     </para>
 1790 
 1791 <programlisting>
 1792 search ...
 1793 nameserver 172.16.72.2
 1794 nameserver 172.16.72.3
 1795 nameserver 172.16.72.4
 1796 </programlisting>
 1797 
 1798       </section>
 1799     </section>
 1800     <section xml:id="tsig"><info><title>TSIG</title></info>
 1801 
 1802       <para>
 1803     TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS
 1804     messages, originally specified in RFC 2845. It allows DNS messages
 1805     to be cryptographically signed using a shared secret.  TSIG can
 1806     be used in any DNS transaction, as a way to restrict access to
 1807     certain server functions (e.g., recursive queries) to authorized
 1808     clients when IP-based access control is insufficient or needs to
 1809     be overridden, or as a way to ensure message authenticity when it
 1810     is critical to the integrity of the server, such as with dynamic
 1811     UPDATE messages or zone transfers from a primary to a secondary server.
 1812       </para>
 1813       <para>
 1814     This section is a guide to setting up TSIG in <acronym>BIND</acronym>.
 1815     It describes the configuration syntax and the process of creating
 1816     TSIG keys.
 1817       </para>
 1818       <para>
 1819     <command>named</command> supports TSIG for server-to-server
 1820     communication, and some of the tools included with
 1821     <acronym>BIND</acronym> support it for sending messages to
 1822     <command>named</command>:
 1823     <itemizedlist>
 1824       <listitem>
 1825         <xref linkend="man.nsupdate"/> supports TSIG via the
 1826         <option>-k</option>, <option>-l</option>, and
 1827         <option>-y</option> command-line options, or via
 1828         the <command>key</command> command when running
 1829         interactively.
 1830       </listitem>
 1831       <listitem>
 1832         <xref linkend="man.dig"/> supports TSIG via the
 1833         <option>-k</option> and <option>-y</option>
 1834         command-line options.
 1835       </listitem>
 1836     </itemizedlist>
 1837       </para>
 1838 
 1839       <section><info><title>Generating a Shared Key</title></info>
 1840     <para>
 1841       TSIG keys can be generated using the <command>tsig-keygen</command>
 1842       command; the output of the command is a <command>key</command> directive
 1843       suitable for inclusion in <filename>named.conf</filename>.  The
 1844       key name, algorithm, and size can be specified by command-line parameters;
 1845       the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively.
 1846     </para>
 1847     <para>
 1848       Any string which is a valid DNS name can be used as a key name.
 1849       For example, a key to be shared between servers called
 1850       <emphasis>host1</emphasis> and <emphasis>host2</emphasis> could
 1851       be called "host1-host2.", and this key can be generated using:
 1852     </para>
 1853 <programlisting>
 1854   $ tsig-keygen host1-host2. > host1-host2.key
 1855 </programlisting>
 1856     <para>
 1857       This key may then be copied to both hosts.  The key name and secret
 1858       must be identical on both hosts.
 1859       (Note: copying a shared secret from one server to another is beyond
 1860       the scope of the DNS. A secure transport mechanism should be used:
 1861       secure FTP, SSL, ssh, telephone, encrypted email, etc.)
 1862     </para>
 1863     <para>
 1864       <command>tsig-keygen</command> can also be run as
 1865       <command>ddns-confgen</command>, in which case its output includes
 1866       additional configuration text for setting up dynamic DNS in
 1867       <command>named</command>.  See <xref linkend="man.ddns-confgen"/>
 1868       for details.
 1869     </para>
 1870       </section>
 1871 
 1872       <section><info><title>Loading a New Key</title></info>
 1873     <para>
 1874       For a key shared between servers called
 1875       <emphasis>host1</emphasis> and <emphasis>host2</emphasis>,
 1876       the following could be added to each server's
 1877       <filename>named.conf</filename> file:
 1878     </para>
 1879 <programlisting>
 1880 key "host1-host2." {
 1881     algorithm hmac-sha256;
 1882     secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
 1883 };
 1884 </programlisting>
 1885     <para>
 1886       (This is the same key generated above using
 1887       <command>tsig-keygen</command>.)
 1888     </para>
 1889     <para>
 1890       Since this text contains a secret, it
 1891       is recommended that either <filename>named.conf</filename> not be
 1892       world-readable, or that the <command>key</command> directive
 1893       be stored in a file which is not world-readable and which is
 1894       included in <filename>named.conf</filename> via the
 1895       <command>include</command> directive.
 1896     </para>
 1897     <para>
 1898       Once a key has been added to <filename>named.conf</filename> and the
 1899       server has been restarted or reconfigured, the server can recognize
 1900       the key.  If the server receives a message signed by the
 1901       key, it is able to verify the signature.  If the signature
 1902       is valid, the response is signed using the same key.
 1903     </para>
 1904     <para>
 1905       TSIG keys that are known to a server can be listed using the
 1906       command <command>rndc tsig-list</command>.
 1907     </para>
 1908       </section>
 1909 
 1910       <section><info><title>Instructing the Server to Use a Key</title></info>
 1911     <para>
 1912       A server sending a request to another server must be told whether
 1913       to use a key, and if so, which key to use.
 1914     </para>
 1915     <para>
 1916       For example, a key may be specified for each server in the
 1917       <command>masters</command> statement in the definition of a
 1918       secondary zone; in this case, all SOA QUERY messages, NOTIFY
 1919       messages, and zone transfer requests (AXFR or IXFR) are
 1920       signed using the specified key.  Keys may also be specified
 1921       in the <command>also-notify</command> statement of a primary
 1922       or secondary zone, causing NOTIFY messages to be signed using
 1923       the specified key.
 1924     </para>
 1925     <para>
 1926       Keys can also be specified in a <command>server</command>
 1927       directive. Adding the following on <emphasis>host1</emphasis>,
 1928       if the IP address of <emphasis>host2</emphasis> is 10.1.2.3, would
 1929       cause <emphasis>all</emphasis> requests from <emphasis>host1</emphasis>
 1930       to <emphasis>host2</emphasis>, including normal DNS queries, to be
 1931       signed using the <command>host1-host2.</command> key:
 1932     </para>
 1933 <programlisting>
 1934 server 10.1.2.3 {
 1935     keys { host1-host2. ;};
 1936 };
 1937 </programlisting>
 1938     <para>
 1939       Multiple keys may be present in the <command>keys</command>
 1940       statement, but only the first one is used.  As this directive does
 1941       not contain secrets, it can be used in a world-readable file.
 1942     </para>
 1943     <para>
 1944       Requests sent by <emphasis>host2</emphasis> to <emphasis>host1</emphasis>
 1945       would <emphasis>not</emphasis> be signed, unless a similar
 1946       <command>server</command> directive were in <emphasis>host2</emphasis>'s
 1947       configuration file.
 1948     </para>
 1949     <para>
 1950       Whenever any server sends a TSIG-signed DNS request, it expects
 1951       the response to be signed with the same key. If a response is not
 1952       signed, or if the signature is not valid, the response is
 1953       rejected.
 1954     </para>
 1955       </section>
 1956 
 1957       <section><info><title>TSIG-Based Access Control</title></info>
 1958     <para>
 1959       TSIG keys may be specified in ACL definitions and ACL directives
 1960       such as <command>allow-query</command>, <command>allow-transfer</command>,
 1961       and <command>allow-update</command>.
 1962       The above key would be denoted in an ACL element as
 1963       <command>key host1-host2.</command>
 1964     </para>
 1965     <para>
 1966       Here is an example of an <command>allow-update</command> directive using
 1967       a TSIG key:
 1968     </para>
 1969 <programlisting>
 1970 allow-update { !{ !localnets; any; }; key host1-host2. ;};
 1971 </programlisting>
 1972     <para>
 1973       This allows dynamic updates to succeed only if the UPDATE
 1974       request comes from an address in <command>localnets</command>,
 1975       <emphasis>and</emphasis> if it is signed using the
 1976       <command>host1-host2.</command> key.
 1977     </para>
 1978     <para>
 1979       See <xref linkend="dynamic_update_policies"/> for a discussion of
 1980       the more flexible <command>update-policy</command> statement.
 1981     </para>
 1982       </section>
 1983 
 1984       <section><info><title>Errors</title></info>
 1985     <para>
 1986       Processing of TSIG-signed messages can result in several errors:
 1987       <itemizedlist>
 1988         <listitem>
 1989           If a TSIG-aware server receives a message signed by an
 1990           unknown key, the response will be unsigned, with the TSIG
 1991           extended error code set to BADKEY.
 1992         </listitem>
 1993         <listitem>
 1994           If a TSIG-aware server receives a message from a known key
 1995           but with an invalid signature, the response will be unsigned,
 1996           with the TSIG extended error code set to BADSIG.
 1997         </listitem>
 1998         <listitem>
 1999           If a TSIG-aware server receives a message with a time
 2000           outside of the allowed range, the response will be signed but
 2001           the TSIG extended error code set to BADTIME, and the time values
 2002           will be adjusted so that the response can be successfully
 2003           verified.
 2004         </listitem>
 2005       </itemizedlist>
 2006       In all of the above cases, the server returns a response code
 2007       of NOTAUTH (not authenticated).
 2008     </para>
 2009       </section>
 2010     </section>
 2011 
 2012     <section xml:id="tkey"><info><title>TKEY</title></info>
 2013 
 2014       <para>
 2015     TKEY (Transaction KEY) is a mechanism for automatically negotiating
 2016     a shared secret between two hosts, originally specified in RFC 2930.
 2017       </para>
 2018       <para>
 2019     There are several TKEY "modes" that specify how a key is to be
 2020     generated or assigned.  <acronym>BIND</acronym> 9 implements only
 2021     one of these modes: Diffie-Hellman key exchange.  Both hosts are
 2022     required to have a KEY record with algorithm DH (though this
 2023     record is not required to be present in a zone).
 2024       </para>
 2025       <para>
 2026     The TKEY process is initiated by a client or server by sending
 2027     a query of type TKEY to a TKEY-aware server.  The query must include
 2028     an appropriate KEY record in the additional section, and
 2029     must be signed using either TSIG or SIG(0) with a previously
 2030     established key.  The server's response, if successful,
 2031     contains a TKEY record in its answer section.  After this transaction,
 2032     both participants have enough information to calculate a
 2033     shared secret using Diffie-Hellman key exchange.  The shared secret
 2034     can then be used by to sign subsequent transactions between the
 2035     two servers.
 2036       </para>
 2037       <para>
 2038     TSIG keys known by the server, including TKEY-negotiated keys, can
 2039     be listed using <command>rndc tsig-list</command>.
 2040       </para>
 2041       <para>
 2042     TKEY-negotiated keys can be deleted from a server using
 2043     <command>rndc tsig-delete</command>.  This can also be done via
 2044     the TKEY protocol itself, by sending an authenticated TKEY query
 2045     specifying the "key deletion" mode.
 2046       </para>
 2047 
 2048     </section>
 2049     <section xml:id="sig0"><info><title>SIG(0)</title></info>
 2050 
 2051       <para>
 2052     <acronym>BIND</acronym> partially supports DNSSEC SIG(0)
 2053     transaction signatures as specified in RFC 2535 and RFC 2931.
 2054     SIG(0) uses public/private keys to authenticate messages.  Access control
 2055     is performed in the same manner as with TSIG keys; privileges can be
 2056     granted or denied in ACL directives based on the key name.
 2057       </para>
 2058       <para>
 2059     When a SIG(0) signed message is received, it is only
 2060     verified if the key is known and trusted by the server. The
 2061     server does not attempt to recursively fetch or validate the
 2062     key.
 2063       </para>
 2064       <para>
 2065     SIG(0) signing of multiple-message TCP streams is not supported.
 2066       </para>
 2067       <para>
 2068     The only tool shipped with <acronym>BIND</acronym> 9 that
 2069     generates SIG(0) signed messages is <command>nsupdate</command>.
 2070       </para>
 2071     </section>
 2072 
 2073     <section xml:id="DNSSEC"><info><title>DNSSEC</title></info>
 2074       <para>
 2075     Cryptographic authentication of DNS information is possible
 2076     through the DNS Security (<emphasis>DNSSEC-bis</emphasis>) extensions,
 2077     defined in RFC 4033, RFC 4034, and RFC 4035.
 2078     This section describes the creation and use of DNSSEC signed zones.
 2079       </para>
 2080 
 2081       <para>
 2082     In order to set up a DNSSEC secure zone, there are a series
 2083     of steps which must be followed.  <acronym>BIND</acronym>
 2084     9 ships
 2085     with several tools
 2086     that are used in this process, which are explained in more detail
 2087     below.  In all cases, the <option>-h</option> option prints a
 2088     full list of parameters.  Note that the DNSSEC tools require the
 2089     keyset files to be in the working directory or the
 2090     directory specified by the <option>-d</option> option.
 2091       </para>
 2092 
 2093       <para>
 2094     There must also be communication with the administrators of
 2095     the parent and/or child zone to transmit keys.  A zone's security
 2096     status must be indicated by the parent zone for a DNSSEC-capable
 2097     resolver to trust its data.  This is done through the presence
 2098     or absence of a <literal>DS</literal> record at the
 2099     delegation
 2100     point.
 2101       </para>
 2102 
 2103       <para>
 2104     For other servers to trust data in this zone, they must
 2105     be statically configured with either this zone's zone key or the
 2106     zone key of another zone above this one in the DNS tree.
 2107       </para>
 2108 
 2109       <section xml:id="dnssec_keys"><info><title>Generating Keys</title></info>
 2110 
 2111     <para>
 2112       The <command>dnssec-keygen</command> program is used to
 2113       generate keys.
 2114     </para>
 2115 
 2116     <para>
 2117       A secure zone must contain one or more zone keys.  The
 2118       zone keys will sign all other records in the zone, as well as
 2119       the zone keys of any secure delegated zones.  Zone keys must
 2120       have the same name as the zone, have a name type of
 2121       <command>ZONE</command>, and be usable for
 2122       authentication.
 2123       It is recommended that zone keys use a cryptographic algorithm
 2124       designated as "mandatory to implement" by the IETF; currently
 2125       the only one is RSASHA1.
 2126     </para>
 2127 
 2128     <para>
 2129       The following command generates a 768-bit RSASHA1 key for
 2130       the <filename>child.example</filename> zone:
 2131     </para>
 2132 
 2133     <para>
 2134       <userinput>dnssec-keygen -a RSASHA1 -b 768 -n ZONE child.example.</userinput>
 2135     </para>
 2136 
 2137     <para>
 2138       Two output files are produced:
 2139       <filename>Kchild.example.+005+12345.key</filename> and
 2140       <filename>Kchild.example.+005+12345.private</filename>
 2141       (where
 2142       12345 is an example of a key tag).  The key filenames contain
 2143       the key name (<filename>child.example.</filename>), the
 2144       algorithm (3
 2145       is DSA, 1 is RSAMD5, 5 is RSASHA1, etc.), and the key tag (12345 in
 2146       this case).
 2147       The private key (in the <filename>.private</filename>
 2148       file) is
 2149       used to generate signatures, and the public key (in the
 2150       <filename>.key</filename> file) is used for signature
 2151       verification.
 2152     </para>
 2153 
 2154     <para>
 2155       To generate another key with the same properties but with
 2156       a different key tag, repeat the above command.
 2157     </para>
 2158 
 2159     <para>
 2160       The <command>dnssec-keyfromlabel</command> program is used
 2161       to get a key pair from a crypto hardware device and build the key
 2162       files. Its usage is similar to <command>dnssec-keygen</command>.
 2163     </para>
 2164 
 2165     <para>
 2166       The public keys should be inserted into the zone file by
 2167       including the <filename>.key</filename> files using
 2168       <command>$INCLUDE</command> statements.
 2169     </para>
 2170 
 2171       </section>
 2172       <section xml:id="dnssec_signing"><info><title>Signing the Zone</title></info>
 2173 
 2174     <para>
 2175       The <command>dnssec-signzone</command> program is used
 2176       to sign a zone.
 2177     </para>
 2178 
 2179     <para>
 2180       Any <filename>keyset</filename> files corresponding to
 2181       secure sub-zones should be present.  The zone signer
 2182       generates <literal>NSEC</literal>, <literal>NSEC3</literal>,
 2183       and <literal>RRSIG</literal> records for the zone, as
 2184       well as <literal>DS</literal> for the child zones if
 2185       <literal>-g</literal> is specified.  If <literal>-g</literal>
 2186       is not specified, then DS RRsets for the secure child
 2187       zones need to be added manually.
 2188     </para>
 2189 
 2190     <para>
 2191       By default, all zone keys which have an available private key are
 2192       used to generate signatures. The following command signs the zone, assuming it is in a
 2193       file called <filename>zone.child.example</filename>:
 2194     </para>
 2195 
 2196     <para>
 2197       <userinput>dnssec-signzone -o child.example zone.child.example</userinput>
 2198     </para>
 2199 
 2200     <para>
 2201       One output file is produced:
 2202       <filename>zone.child.example.signed</filename>.  This
 2203       file
 2204       should be referenced by <filename>named.conf</filename>
 2205       as the
 2206       input file for the zone.
 2207     </para>
 2208 
 2209     <para><command>dnssec-signzone</command>
 2210       also produces keyset and dsset files.
 2211       These are used to provide the parent zone
 2212       administrators with the <literal>DNSKEYs</literal> (or their
 2213       corresponding <literal>DS</literal> records) that are the
 2214       secure entry point to the zone.
 2215     </para>
 2216 
 2217       </section>
 2218 
 2219       <section xml:id="dnssec_config"><info><title>Configuring Servers for DNSSEC</title></info>
 2220 
 2221     <para>
 2222       To enable <command>named</command> to respond appropriately
 2223       to DNS requests from DNSSEC-aware clients,
 2224       <command>dnssec-enable</command> must be set to yes.
 2225       (This is the default setting.)
 2226     </para>
 2227 
 2228     <para>
 2229       To enable <command>named</command> to validate answers from
 2230       other servers, the <command>dnssec-enable</command> option
 2231       must be set to <userinput>yes</userinput>, and the
 2232       <command>dnssec-validation</command> option must be set to
 2233       <userinput>yes</userinput> or <userinput>auto</userinput>.
 2234     </para>
 2235 
 2236     <para>
 2237       If <command>dnssec-validation</command> is set to
 2238       <userinput>auto</userinput>, then a default
 2239       trust anchor for the DNS root zone is used.
 2240       If it is set to <userinput>yes</userinput>, however,
 2241       then at least one trust anchor must be configured
 2242       with a <command>trusted-keys</command> or
 2243       <command>managed-keys</command> statement in
 2244       <filename>named.conf</filename>, or DNSSEC validation
 2245       will not occur.  The default setting is
 2246       <userinput>yes</userinput>.
 2247     </para>
 2248 
 2249     <para>
 2250       <command>trusted-keys</command> are copies of DNSKEY RRs
 2251       for zones that are used to form the first link in the
 2252       cryptographic chain of trust.  All keys listed in
 2253       <command>trusted-keys</command> (and corresponding zones)
 2254       are deemed to exist and only the listed keys are used
 2255       to validate the DNSKEY RRset that they are from.
 2256     </para>
 2257 
 2258     <para>
 2259       <command>managed-keys</command> are trusted keys which are
 2260       automatically kept up-to-date via RFC 5011 trust anchor
 2261       maintenance.
 2262     </para>
 2263 
 2264     <para>
 2265       <command>trusted-keys</command> and
 2266       <command>managed-keys</command> are described in more detail
 2267       later in this document.
 2268     </para>
 2269 
 2270     <para>
 2271       <acronym>BIND</acronym>
 2272       9 does not verify signatures on load, so zone keys for
 2273       authoritative zones do not need to be specified in the
 2274       configuration file.
 2275     </para>
 2276 
 2277     <para>
 2278       After DNSSEC is established, a typical DNSSEC configuration
 2279       looks something like the following.  It has one or
 2280       more public keys for the root, which allows answers from
 2281       outside the organization to be validated.  It also
 2282       has several keys for parts of the namespace that the organization
 2283       controls.  These are here to ensure that <command>named</command>
 2284       is immune to compromised security in the DNSSEC components
 2285       of parent zones.
 2286     </para>
 2287 
 2288 <programlisting>
 2289 managed-keys {
 2290     /* Root Key */
 2291     "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS
 2292                  JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh
 2293                  aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy
 2294                  4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg
 2295                  hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp
 2296                  5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke
 2297                  g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq
 2298                  66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ
 2299                  97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ
 2300                  dgxbcDTClU0CRBdiieyLMNzXG3";
 2301 };
 2302 
 2303 trusted-keys {
 2304     /* Key for our organization's forward zone */
 2305     example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6
 2306                   5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z
 2307                   GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb
 2308                   4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL
 2309                   kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O
 2310                   g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S
 2311                   TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq
 2312                   FxmAVZP20igTixin/1LcrgX/KMEGd/biuv
 2313                   F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm
 2314                   /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o
 2315                   1OTQ09A0=";
 2316 
 2317     /* Key for our reverse zone. */
 2318     2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
 2319                        xOdNax071L18QqZnQQQAVVr+i
 2320                        LhGTnNGp3HoWQLUIzKrJVZ3zg
 2321                        gy3WwNT6kZo6c0tszYqbtvchm
 2322                        gQC8CzKojM/W16i6MG/eafGU3
 2323                        siaOdS0yOI6BgPsw+YZdzlYMa
 2324                        IJGf4M4dyoKIhzdZyQ2bYQrjy
 2325                        Q4LB0lC7aOnsMyYKHHYeRvPxj
 2326                        IQXmdqgOJGq+vsevG06zW+1xg
 2327                        YJh9rCIfnm1GX/KMgxLPG2vXT
 2328                        D/RnLX+D3T3UL7HJYHJhAZD5L
 2329                        59VvjSPsZJHeDCUyWYrvPZesZ
 2330                        DIRvhDD52SKvbheeTJUm6Ehkz
 2331                        ytNN2SN96QRk8j/iI8ib";
 2332 };
 2333 
 2334 options {
 2335     ...
 2336     dnssec-enable yes;
 2337     dnssec-validation yes;
 2338 };
 2339 </programlisting>
 2340 
 2341     <note><simpara>
 2342       None of the keys listed in this example are valid.  In particular,
 2343       the root key is not valid.
 2344     </simpara></note>
 2345 
 2346     <para>
 2347       When DNSSEC validation is enabled and properly configured,
 2348       the resolver rejects any answers from signed, secure zones
 2349       which fail to validate, and returns SERVFAIL to the client.
 2350     </para>
 2351 
 2352     <para>
 2353       Responses may fail to validate for any of several reasons,
 2354       including missing, expired, or invalid signatures, a key which
 2355       does not match the DS RRset in the parent zone, or an insecure
 2356       response from a zone which, according to its parent, should have
 2357       been secure.
 2358     </para>
 2359 
 2360     <note>
 2361       <para>
 2362         When the validator receives a response from an unsigned zone
 2363         that has a signed parent, it must confirm with the parent
 2364         that the zone was intentionally left unsigned.  It does
 2365         this by verifying, via signed and validated NSEC/NSEC3 records,
 2366         that the parent zone contains no DS records for the child.
 2367       </para>
 2368       <para>
 2369         If the validator <emphasis>can</emphasis> prove that the zone
 2370         is insecure, then the response is accepted.  However, if it
 2371         cannot, the validator must assume an insecure response to be a
 2372         forgery; it rejects the response and logs an error.
 2373       </para>
 2374       <para>
 2375         The logged error reads "insecurity proof failed" and
 2376         "got insecure response; parent indicates it should be secure".
 2377       </para>
 2378     </note>
 2379       </section>
 2380     </section>
 2381 
 2382     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dnssec.xml"/>
 2383 
 2384     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="managed-keys.xml"/>
 2385 
 2386     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pkcs11.xml"/>
 2387 
 2388     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dlz.xml"/>
 2389 
 2390     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dyndb.xml"/>
 2391 
 2392     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="catz.xml"/>
 2393 
 2394     <section xml:id="ipv6"><info><title>IPv6 Support in <acronym>BIND</acronym> 9</title></info>
 2395       <para>
 2396     <acronym>BIND</acronym> 9 fully supports all currently
 2397     defined forms of IPv6 name-to-address and address-to-name
 2398     lookups.  It also uses IPv6 addresses to make queries when
 2399     running on an IPv6-capable system.
 2400       </para>
 2401 
 2402       <para>
 2403     For forward lookups, <acronym>BIND</acronym> 9 supports
 2404     only AAAA records.  RFC 3363 deprecated the use of A6 records,
 2405     and client-side support for A6 records was accordingly removed
 2406     from <acronym>BIND</acronym> 9.
 2407     However, authoritative <acronym>BIND</acronym> 9 name servers still
 2408     load zone files containing A6 records correctly, answer queries
 2409     for A6 records, and accept zone transfer for a zone containing A6
 2410     records.
 2411       </para>
 2412 
 2413       <para>
 2414     For IPv6 reverse lookups, <acronym>BIND</acronym> 9 supports
 2415     the traditional "nibble" format used in the
 2416     <emphasis>ip6.arpa</emphasis> domain, as well as the older, deprecated
 2417     <emphasis>ip6.int</emphasis> domain.
 2418     Older versions of <acronym>BIND</acronym> 9
 2419     supported the "binary label" (also known as "bitstring") format,
 2420     but support of binary labels has been completely removed per
 2421     RFC 3363.
 2422     Many applications in <acronym>BIND</acronym> 9 do not understand
 2423     the binary label format at all anymore, and return an
 2424     error if one is given.
 2425     In particular, an authoritative <acronym>BIND</acronym> 9
 2426     name server will not load a zone file containing binary labels.
 2427       </para>
 2428 
 2429       <para>
 2430     For an overview of the format and structure of IPv6 addresses,
 2431     see <xref linkend="ipv6addresses"/>.
 2432       </para>
 2433 
 2434       <section><info><title>Address Lookups Using AAAA Records</title></info>
 2435 
 2436     <para>
 2437       The IPv6 AAAA record is a parallel to the IPv4 A record,
 2438       and, unlike the deprecated A6 record, specifies the entire
 2439       IPv6 address in a single record.  For example:
 2440     </para>
 2441 
 2442 <programlisting>
 2443 $ORIGIN example.com.
 2444 host            3600    IN      AAAA    2001:db8::1
 2445 </programlisting>
 2446 
 2447     <para>
 2448       Use of IPv4-in-IPv6 mapped addresses is not recommended.
 2449       If a host has an IPv4 address, use an A record, not
 2450       a AAAA, with <literal>::ffff:192.168.42.1</literal> as
 2451       the address.
 2452     </para>
 2453       </section>
 2454       <section><info><title>Address-to-Name Lookups Using Nibble Format</title></info>
 2455 
 2456     <para>
 2457       When looking up an address in nibble format, the address
 2458       components are simply reversed, just as in IPv4, and
 2459       <literal>ip6.arpa.</literal> is appended to the
 2460       resulting name.
 2461       For example, the following would provide reverse name lookup for
 2462       a host with address
 2463       <literal>2001:db8::1</literal>:
 2464     </para>
 2465 
 2466 <programlisting>
 2467 $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa.
 2468 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0  14400   IN    PTR    (
 2469                     host.example.com. )
 2470 </programlisting>
 2471 
 2472       </section>
 2473     </section>
 2474   </chapter>
 2475 
 2476   <chapter xml:id="Bv9ARM.ch05"><info><title>The <acronym>BIND</acronym> 9 Lightweight Resolver</title></info>
 2477 
 2478     <section xml:id="lightweight_resolver"><info><title>The Lightweight Resolver Library</title></info>
 2479 
 2480       <para>
 2481     Traditionally, applications have been linked with a stub resolver
 2482     library that sends recursive DNS queries to a local caching name
 2483     server.
 2484       </para>
 2485       <para>
 2486     At first, IPv6 introduced new complexity into the resolution process,
 2487     such as following A6 chains and DNAME records, and simultaneous
 2488     lookup of IPv4 and IPv6 addresses.  Though most of the complexity was
 2489     then removed, these are hard or impossible
 2490     to implement in a traditional stub resolver.
 2491       </para>
 2492       <para>
 2493     <acronym>BIND</acronym> 9 therefore can also provide resolution
 2494     services to local clients
 2495     using a combination of a lightweight resolver library and a resolver
 2496     daemon process running on the local host.  These communicate using
 2497     a simple UDP-based protocol, the "lightweight resolver protocol,"
 2498     that is distinct from and simpler than the full DNS protocol.
 2499       </para>
 2500     </section>
 2501     <section xml:id="lwresd"><info><title>Running a Resolver Daemon</title></info>
 2502 
 2503       <para>
 2504     To use the lightweight resolver interface, the system must
 2505     run the resolver daemon <command>lwresd</command> or a
 2506     local
 2507     name server configured with a <command>lwres</command>
 2508     statement.
 2509       </para>
 2510 
 2511       <para>
 2512     By default, applications using the lightweight resolver library
 2513     make
 2514     UDP requests to the IPv4 loopback address (127.0.0.1) on port 921.
 2515     The
 2516     address can be overridden by <command>lwserver</command>
 2517     lines in
 2518     <filename>/etc/resolv.conf</filename>.
 2519       </para>
 2520 
 2521       <para>
 2522     The <command>lwresd</command> daemon is essentially a
 2523     caching-only name server that responds to requests using the
 2524     lightweight
 2525     resolver protocol rather than the DNS protocol.  Because it needs
 2526     to run on each host, it is designed to require no or minimal
 2527     configuration.
 2528     Unless otherwise instructed, it uses the name servers listed on
 2529     <command>nameserver</command> lines in <filename>/etc/resolv.conf</filename>
 2530     as forwarders, but is also capable of doing the resolution
 2531     autonomously if
 2532     none are specified.
 2533       </para>
 2534       <para>
 2535     The <command>lwresd</command> daemon may also be
 2536     configured with a
 2537     <filename>named.conf</filename>-style configuration file,
 2538     in
 2539     <filename>/etc/lwresd.conf</filename> by default.  A name
 2540     server may also
 2541     be configured to act as a lightweight resolver daemon using the
 2542     <command>lwres</command> statement in <filename>named.conf</filename>.
 2543       </para>
 2544       <para>
 2545     The number of client queries that the <command>lwresd</command>
 2546     daemon serves can be set using the
 2547     <option>lwres-tasks</option> and <option>lwres-clients</option>
 2548     statements in the configuration.
 2549       </para>
 2550     </section>
 2551   </chapter>
 2552 
 2553   <chapter xml:id="Bv9ARM.ch06"><info><title><acronym>BIND</acronym> 9 Configuration Reference</title></info>
 2554 
 2555     <section xml:id="configuration_file_elements"><info><title>Configuration File Elements</title></info>
 2556 
 2557       <para>
 2558     Following is a list of elements used throughout the <acronym>BIND</acronym> configuration
 2559     file documentation:
 2560       </para>
 2561       <informaltable colsep="0" rowsep="0">
 2562     <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
 2563       <colspec colname="1" colnum="1" colsep="0" colwidth="1.855in"/>
 2564       <colspec colname="2" colnum="2" colsep="0" colwidth="3.770in"/>
 2565       <tbody>
 2566         <row rowsep="0">
 2567           <entry colname="1">
 2568         <para>
 2569           <varname>acl_name</varname>
 2570         </para>
 2571           </entry>
 2572           <entry colname="2">
 2573         <para>
 2574           The name of an <varname>address_match_list</varname> as
 2575           defined by the <command>acl</command> statement.
 2576         </para>
 2577           </entry>
 2578         </row>
 2579         <row rowsep="0">
 2580           <entry colname="1">
 2581         <para>
 2582           <varname>address_match_list</varname>
 2583         </para>
 2584           </entry>
 2585           <entry colname="2">
 2586         <para>
 2587           A list of one or more
 2588           <varname>ip_addr</varname>,
 2589           <varname>ip_prefix</varname>, <varname>key_id</varname>,
 2590           or <varname>acl_name</varname> elements; see
 2591           <xref linkend="address_match_lists"/>.
 2592         </para>
 2593           </entry>
 2594         </row>
 2595         <row rowsep="0">
 2596           <entry colname="1">
 2597         <para>
 2598           <varname>masters_list</varname>
 2599         </para>
 2600           </entry>
 2601           <entry colname="2">
 2602         <para>
 2603           A named list of one or more <varname>ip_addr</varname>
 2604           with optional <varname>key_id</varname> and/or
 2605           <varname>ip_port</varname>.
 2606           A <varname>masters_list</varname> may include other
 2607           <varname>masters_list</varname>s.
 2608         </para>
 2609           </entry>
 2610         </row>
 2611         <row rowsep="0">
 2612           <entry colname="1">
 2613         <para>
 2614           <varname>domain_name</varname>
 2615         </para>
 2616           </entry>
 2617           <entry colname="2">
 2618         <para>
 2619           A quoted string which is used as
 2620           a DNS name; for example, <literal>my.test.domain</literal>.
 2621         </para>
 2622           </entry>
 2623         </row>
 2624         <row rowsep="0">
 2625           <entry colname="1">
 2626         <para>
 2627           <varname>namelist</varname>
 2628         </para>
 2629           </entry>
 2630           <entry colname="2">
 2631         <para>
 2632           A list of one or more <varname>domain_name</varname>
 2633           elements.
 2634         </para>
 2635           </entry>
 2636         </row>
 2637         <row rowsep="0">
 2638           <entry colname="1">
 2639         <para>
 2640           <varname>dotted_decimal</varname>
 2641         </para>
 2642           </entry>
 2643           <entry colname="2">
 2644         <para>
 2645           One to four integers valued 0 through
 2646           255 separated by dots ("."), such as <command>123.45.67</command> or <command>89.123.45.67</command>.
 2647         </para>
 2648           </entry>
 2649         </row>
 2650         <row rowsep="0">
 2651           <entry colname="1">
 2652         <para>
 2653           <varname>ip4_addr</varname>
 2654         </para>
 2655           </entry>
 2656           <entry colname="2">
 2657         <para>
 2658           An IPv4 address with exactly four elements
 2659           in <varname>dotted_decimal</varname> notation.
 2660         </para>
 2661           </entry>
 2662         </row>
 2663         <row rowsep="0">
 2664           <entry colname="1">
 2665         <para>
 2666           <varname>ip6_addr</varname>
 2667         </para>
 2668           </entry>
 2669           <entry colname="2">
 2670         <para>
 2671           An IPv6 address, such as <command>2001:db8::1234</command>.
 2672           IPv6-scoped addresses that have ambiguity on their
 2673           scope zones must be disambiguated by an appropriate
 2674           zone ID with the percent character ("%") as a
 2675           delimiter.  It is strongly recommended to use
 2676           string zone names rather than numeric identifiers,
 2677           to be robust against system configuration
 2678           changes.  However, since there is no standard
 2679           mapping for such names and identifier values,
 2680           only interface names as link identifiers
 2681           are supported, assuming one-to-one mapping between
 2682           interfaces and links.  For example, a link-local
 2683           address <command>fe80::1</command> on the link
 2684           attached to the interface <command>ne0</command>
 2685           can be specified as <command>fe80::1%ne0</command>.
 2686           Note that on most systems link-local addresses
 2687           always have ambiguity and need to be
 2688           disambiguated.
 2689         </para>
 2690           </entry>
 2691         </row>
 2692         <row rowsep="0">
 2693           <entry colname="1">
 2694         <para>
 2695           <varname>ip_addr</varname>
 2696         </para>
 2697           </entry>
 2698           <entry colname="2">
 2699         <para>
 2700           An <varname>ip4_addr</varname> or <varname>ip6_addr</varname>.
 2701         </para>
 2702           </entry>
 2703         </row>
 2704         <row rowsep="0">
 2705           <entry colname="1">
 2706         <para>
 2707           <varname>ip_dscp</varname>
 2708         </para>
 2709           </entry>
 2710           <entry colname="2">
 2711         <para>
 2712           A <varname>number</varname> between 0 and 63, used
 2713           to select a differentiated services code point (DSCP)
 2714           value for use with outgoing traffic on operating systems
 2715           that support DSCP.
 2716         </para>
 2717           </entry>
 2718         </row>
 2719         <row rowsep="0">
 2720           <entry colname="1">
 2721         <para>
 2722           <varname>ip_port</varname>
 2723         </para>
 2724           </entry>
 2725           <entry colname="2">
 2726         <para>
 2727           An IP port <varname>number</varname>.
 2728           The <varname>number</varname> is limited to 0
 2729           through 65535, with values
 2730           below 1024 typically restricted to use by processes running
 2731           as root.
 2732           In some cases, an asterisk ("*") character can be used as a
 2733           placeholder to
 2734           select a random high-numbered port.
 2735         </para>
 2736           </entry>
 2737         </row>
 2738         <row rowsep="0">
 2739           <entry colname="1">
 2740         <para>
 2741           <varname>ip_prefix</varname>
 2742         </para>
 2743           </entry>
 2744           <entry colname="2">
 2745         <para>
 2746           An IP network specified as an <varname>ip_addr</varname>,
 2747           followed by a slash ("/") and then the number of bits in the
 2748           netmask.
 2749           Trailing zeros in an <varname>ip_addr</varname>
 2750           may be omitted.
 2751           For example, <command>127/8</command> is the
 2752           network <command>127.0.0.0</command> with
 2753           netmask <command>255.0.0.0</command> and <command>1.2.3.0/28</command> is
 2754           network <command>1.2.3.0</command> with netmask <command>255.255.255.240</command>.
 2755         </para>
 2756         <para>
 2757           When specifying a prefix involving a IPv6-scoped address,
 2758           the scope may be omitted.  In that case, the prefix
 2759           matches packets from any scope.
 2760         </para>
 2761           </entry>
 2762         </row>
 2763         <row rowsep="0">
 2764           <entry colname="1">
 2765         <para>
 2766           <varname>key_id</varname>
 2767         </para>
 2768           </entry>
 2769           <entry colname="2">
 2770         <para>
 2771           A <varname>domain_name</varname> representing
 2772           the name of a shared key, to be used for transaction
 2773           security.
 2774         </para>
 2775           </entry>
 2776         </row>
 2777         <row rowsep="0">
 2778           <entry colname="1">
 2779         <para>
 2780           <varname>key_list</varname>
 2781         </para>
 2782           </entry>
 2783           <entry colname="2">
 2784         <para>
 2785           A list of one or more
 2786           <varname>key_id</varname>s,
 2787           separated by semicolons and ending with a semicolon.
 2788         </para>
 2789           </entry>
 2790         </row>
 2791         <row rowsep="0">
 2792           <entry colname="1">
 2793         <para>
 2794           <varname>number</varname>
 2795         </para>
 2796           </entry>
 2797           <entry colname="2">
 2798         <para>
 2799           A non-negative 32-bit integer
 2800           (i.e., a number between 0 and 4294967295, inclusive).
 2801           Its acceptable value might be further
 2802           limited by the context in which it is used.
 2803         </para>
 2804           </entry>
 2805         </row>
 2806         <row rowsep="0">
 2807           <entry colname="1">
 2808         <para>
 2809           <varname>fixedpoint</varname>
 2810         </para>
 2811           </entry>
 2812           <entry colname="2">
 2813         <para>
 2814           A non-negative real number that can be specified to
 2815           the nearest one-hundredth.  Up to five digits can be
 2816           specified before a decimal point, and up to two
 2817           digits after, so the maximum value is 99999.99.
 2818           Acceptable values might be further limited by the
 2819           contexts in which they are used.
 2820         </para>
 2821           </entry>
 2822         </row>
 2823         <row rowsep="0">
 2824           <entry colname="1">
 2825         <para>
 2826           <varname>path_name</varname>
 2827         </para>
 2828           </entry>
 2829           <entry colname="2">
 2830         <para>
 2831           A quoted string which is used as
 2832           a pathname, such as <filename>zones/master/my.test.domain</filename>.
 2833         </para>
 2834           </entry>
 2835         </row>
 2836         <row rowsep="0">
 2837           <entry colname="1">
 2838         <para>
 2839           <varname>port_list</varname>
 2840         </para>
 2841           </entry>
 2842           <entry colname="2">
 2843         <para>
 2844           A list of an <varname>ip_port</varname> or a port
 2845           range.
 2846           A port range is specified in the form of
 2847           <userinput>range</userinput> followed by
 2848           two <varname>ip_port</varname>s,
 2849           <varname>port_low</varname> and
 2850           <varname>port_high</varname>, which represents
 2851           port numbers from <varname>port_low</varname> through
 2852           <varname>port_high</varname>, inclusive.
 2853           <varname>port_low</varname> must not be larger than
 2854           <varname>port_high</varname>.
 2855           For example,
 2856           <userinput>range 1024 65535</userinput> represents
 2857           ports from 1024 through 65535.
 2858           In either case an asterisk ("*") character is not
 2859           allowed as a valid <varname>ip_port</varname>.
 2860         </para>
 2861           </entry>
 2862         </row>
 2863         <row rowsep="0">
 2864           <entry colname="1">
 2865         <para>
 2866           <varname>size_spec</varname>
 2867         </para>
 2868           </entry>
 2869           <entry colname="2">
 2870         <para>
 2871           A 64-bit unsigned integer, or the keywords
 2872           <userinput>unlimited</userinput> or
 2873           <userinput>default</userinput>.
 2874         </para>
 2875         <para>
 2876           Integers may take values
 2877           0 &lt;= value &lt;= 18446744073709551615, though
 2878           certain parameters
 2879           (such as <command>max-journal-size</command>) may
 2880           use a more limited range within these extremes.
 2881           In most cases, setting a value to 0 does not
 2882           literally mean zero; it means "undefined" or
 2883           "as big as possible," depending on the context.
 2884           See the explanations of particular parameters
 2885           that use <varname>size_spec</varname>
 2886           for details on how they interpret its use.
 2887         </para>
 2888         <para>
 2889           Numeric values can optionally be followed by a
 2890           scaling factor:
 2891           <userinput>K</userinput> or <userinput>k</userinput>
 2892           for kilobytes,
 2893           <userinput>M</userinput> or <userinput>m</userinput>
 2894           for megabytes, and
 2895           <userinput>G</userinput> or <userinput>g</userinput>
 2896           for gigabytes, which scale by 1024, 1024*1024, and
 2897           1024*1024*1024 respectively.
 2898         </para>
 2899         <para>
 2900           <varname>unlimited</varname> generally means
 2901           "as big as possible," and is usually the best
 2902           way to safely set a very large number.
 2903         </para>
 2904         <para>
 2905           <varname>default</varname>
 2906           uses the limit that was in force when the server was started.
 2907         </para>
 2908           </entry>
 2909         </row>
 2910         <row rowsep="0">
 2911           <entry colname="1">
 2912         <para>
 2913           <varname>size_or_percent</varname>
 2914         </para>
 2915           </entry>
 2916           <entry colname="2">
 2917         <para>
 2918           A <varname>size_spec</varname> or integer value
 2919           followed by "%" to represent percent.
 2920         </para>
 2921         <para>
 2922           The behavior is exactly the same as
 2923           <varname>size_spec</varname>, but
 2924           <varname>size_or_percent</varname> also allows
 2925           specifying a positive integer value followed by the
 2926           "%"" sign to represent percent.
 2927         </para>
 2928           </entry>
 2929         </row>
 2930         <row rowsep="0">
 2931           <entry colname="1">
 2932         <para>
 2933           <varname>yes_or_no</varname>
 2934         </para>
 2935           </entry>
 2936           <entry colname="2">
 2937         <para>
 2938           Either <userinput>yes</userinput> or <userinput>no</userinput>.
 2939           The words <userinput>true</userinput> and <userinput>false</userinput> are
 2940           also accepted, as are the numbers <userinput>1</userinput>
 2941           and <userinput>0</userinput>.
 2942         </para>
 2943           </entry>
 2944         </row>
 2945         <row rowsep="0">
 2946           <entry colname="1">
 2947         <para>
 2948           <varname>dialup_option</varname>
 2949         </para>
 2950           </entry>
 2951           <entry colname="2">
 2952         <para>
 2953           One of <userinput>yes</userinput>,
 2954           <userinput>no</userinput>, <userinput>notify</userinput>,
 2955           <userinput>notify-passive</userinput>, <userinput>refresh</userinput>, or
 2956           <userinput>passive</userinput>.
 2957           When used in a zone, <userinput>notify-passive</userinput>,
 2958           <userinput>refresh</userinput>, and <userinput>passive</userinput>
 2959           are restricted to secondary and stub zones.
 2960         </para>
 2961           </entry>
 2962         </row>
 2963       </tbody>
 2964     </tgroup>
 2965       </informaltable>
 2966       <section xml:id="address_match_lists"><info><title>Address Match Lists</title></info>
 2967 
 2968     <section><info><title>Syntax</title></info>
 2969 
 2970 <programlisting><replaceable>address_match_list</replaceable> = <replaceable>address_match_list_element</replaceable> <command>;</command> ...
 2971 
 2972 <replaceable>address_match_list_element</replaceable> = [ <command>!</command> ] ( <replaceable>ip_address</replaceable> | <replaceable>ip_prefix</replaceable> |
 2973      <command>key</command> <replaceable>key_id</replaceable> | <replaceable>acl_name</replaceable> | <command>{</command> <replaceable>address_match_list</replaceable> <command>}</command> )
 2974 </programlisting>
 2975 
 2976     </section>
 2977     <section><info><title>Definition and Usage</title></info>
 2978 
 2979       <para>
 2980         Address match lists are primarily used to determine access
 2981         control for various server operations. They are also used in
 2982         the <command>listen-on</command> and <command>sortlist</command>
 2983         statements. The elements which constitute an address match
 2984         list can be any of the following:
 2985       </para>
 2986       <itemizedlist>
 2987         <listitem>
 2988           <simpara>an IP address (IPv4 or IPv6)</simpara>
 2989         </listitem>
 2990         <listitem>
 2991           <simpara>an IP prefix (in "/" notation)</simpara>
 2992         </listitem>
 2993         <listitem>
 2994           <simpara>
 2995         a key ID, as defined by the <command>key</command>
 2996         statement
 2997           </simpara>
 2998         </listitem>
 2999         <listitem>
 3000           <simpara>the name of an address match list defined with
 3001         the <command>acl</command> statement
 3002           </simpara>
 3003         </listitem>
 3004         <listitem>
 3005           <simpara>a nested address match list enclosed in braces</simpara>
 3006         </listitem>
 3007       </itemizedlist>
 3008 
 3009       <para>
 3010         Elements can be negated with a leading exclamation mark ("!"),
 3011         and the match list names "any", "none", "localhost", and
 3012         "localnets" are predefined. More information on those names
 3013         can be found in the description of the <command>acl</command>
 3014         statement.
 3015       </para>
 3016 
 3017       <para>
 3018         The addition of the key clause made the name of this syntactic
 3019         element something of a misnomer, since security keys can be used
 3020         to validate access without regard to a host or network address.
 3021         Nonetheless, the term "address match list" is still used
 3022         throughout the documentation.
 3023       </para>
 3024 
 3025       <para>
 3026         When a given IP address or prefix is compared to an address
 3027         match list, the comparison takes place in approximately O(1)
 3028         time.  However, key comparisons require that the list of keys
 3029         be traversed until a matching key is found, and therefore may
 3030         be somewhat slower.
 3031       </para>
 3032 
 3033       <para>
 3034         The interpretation of a match depends on whether the list is being
 3035         used for access control, defining <command>listen-on</command> ports, or in a
 3036         <command>sortlist</command>, and whether the element was negated.
 3037       </para>
 3038 
 3039       <para>
 3040         When used as an access control list, a non-negated match
 3041         allows access and a negated match denies access. If
 3042         there is no match, access is denied. The clauses
 3043         <command>allow-notify</command>,
 3044         <command>allow-recursion</command>,
 3045         <command>allow-recursion-on</command>,
 3046         <command>allow-query</command>,
 3047         <command>allow-query-on</command>,
 3048         <command>allow-query-cache</command>,
 3049         <command>allow-query-cache-on</command>,
 3050         <command>allow-transfer</command>,
 3051         <command>allow-update</command>,
 3052         <command>allow-update-forwarding</command>,
 3053         <command>blackhole</command>, and
 3054         <command>keep-response-order</command> all use address match
 3055         lists.  Similarly, the <command>listen-on</command> option causes the
 3056         server to refuse queries on any of the machine's
 3057         addresses which do not match the list.
 3058       </para>
 3059 
 3060       <para>
 3061         Order of insertion is significant.  If more than one element
 3062         in an ACL is found to match a given IP address or prefix,
 3063         preference is given to the one that came
 3064         <emphasis>first</emphasis> in the ACL definition.
 3065         Because of this first-match behavior, an element that
 3066         defines a subset of another element in the list should
 3067         come before the broader element, regardless of whether
 3068         either is negated. For example, in
 3069         <command>1.2.3/24; ! 1.2.3.13;</command>
 3070         the 1.2.3.13 element is completely useless because the
 3071         algorithm matches any lookup for 1.2.3.13 to the 1.2.3/24
 3072         element.  Using <command>! 1.2.3.13; 1.2.3/24</command> fixes
 3073         that problem by blocking 1.2.3.13 via the negation, but
 3074         all other 1.2.3.* hosts pass through.
 3075       </para>
 3076     </section>
 3077       </section>
 3078 
 3079       <section xml:id="comment_syntax"><info><title>Comment Syntax</title></info>
 3080 
 3081     <para>
 3082       The <acronym>BIND</acronym> 9 comment syntax allows
 3083       comments to appear
 3084       anywhere that whitespace may appear in a <acronym>BIND</acronym> configuration
 3085       file. To appeal to programmers of all kinds, they can be written
 3086       in the C, C++, or shell/perl style.
 3087     </para>
 3088 
 3089     <section><info><title>Syntax</title></info>
 3090 
 3091       <para>
 3092         <programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting>
 3093         <programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting>
 3094         <programlisting># This is a <acronym>BIND</acronym> comment as in common Unix shells
 3095 # and perl</programlisting>
 3096       </para>
 3097     </section>
 3098     <section><info><title>Definition and Usage</title></info>
 3099 
 3100       <para>
 3101         Comments may appear anywhere that whitespace may appear in
 3102         a <acronym>BIND</acronym> configuration file.
 3103       </para>
 3104       <para>
 3105         C-style comments start with the two characters /* (slash,
 3106         star) and end with */ (star, slash). Because they are completely
 3107         delimited with these characters, they can be used to comment only
 3108         a portion of a line or to span multiple lines.
 3109       </para>
 3110       <para>
 3111         C-style comments cannot be nested. For example, the following
 3112         is not valid because the entire comment ends with the first */:
 3113       </para>
 3114       <para>
 3115 
 3116 <programlisting>/* This is the start of a comment.
 3117    This is still part of the comment.
 3118 /* This is an incorrect attempt at nesting a comment. */
 3119    This is no longer in any comment. */
 3120 </programlisting>
 3121 
 3122       </para>
 3123 
 3124       <para>
 3125         C++-style comments start with the two characters // (slash,
 3126         slash) and continue to the end of the physical line. They cannot
 3127         be continued across multiple physical lines; to have one logical
 3128         comment span multiple lines, each line must use the // pair.
 3129         For example:
 3130       </para>
 3131       <para>
 3132 
 3133 <programlisting>// This is the start of a comment.  The next line
 3134 // is a new comment, even though it is logically
 3135 // part of the previous comment.
 3136 </programlisting>
 3137 
 3138       </para>
 3139       <para>
 3140         Shell-style (or perl-style) comments start
 3141         with the character <literal>#</literal> (number sign)
 3142         and continue to the end of the
 3143         physical line, as in C++ comments.
 3144         For example:
 3145       </para>
 3146 
 3147       <para>
 3148 
 3149 <programlisting># This is the start of a comment.  The next line
 3150 # is a new comment, even though it is logically
 3151 # part of the previous comment.
 3152 </programlisting>
 3153 
 3154       </para>
 3155 
 3156       <warning>
 3157         <para>
 3158           The semicolon (";") character
 3159           cannot start a comment, unlike in a zone file. The
 3160           semicolon indicates the end of a configuration
 3161           statement.
 3162         </para>
 3163       </warning>
 3164     </section>
 3165       </section>
 3166     </section>
 3167 
 3168     <section xml:id="Configuration_File_Grammar"><info><title>Configuration File Grammar</title></info>
 3169 
 3170       <para>
 3171     A <acronym>BIND</acronym> 9 configuration consists of
 3172     statements and comments.
 3173     Statements end with a semicolon; statements and comments are the
 3174     only elements that can appear without enclosing braces. Many
 3175     statements contain a block of sub-statements, which are also
 3176     terminated with a semicolon.
 3177       </para>
 3178 
 3179       <para>
 3180     The following statements are supported:
 3181       </para>
 3182 
 3183       <informaltable colsep="0" rowsep="0">
 3184     <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="2Level-table">
 3185       <colspec colname="1" colnum="1" colsep="0" colwidth="1.336in"/>
 3186       <colspec colname="2" colnum="2" colsep="0" colwidth="3.778in"/>
 3187       <tbody>
 3188         <row rowsep="0">
 3189           <entry colname="1">
 3190         <para><command>acl</command></para>
 3191           </entry>
 3192           <entry colname="2">
 3193         <para>
 3194           Defines a named IP address
 3195           matching list, for access control and other uses.
 3196         </para>
 3197           </entry>
 3198         </row>
 3199         <row rowsep="0">
 3200           <entry colname="1">
 3201         <para><command>controls</command></para>
 3202           </entry>
 3203           <entry colname="2">
 3204         <para>
 3205           Declares control channels to be used
 3206           by the <command>rndc</command> utility.
 3207         </para>
 3208           </entry>
 3209         </row>
 3210         <row rowsep="0">
 3211           <entry colname="1">
 3212         <para><command>include</command></para>
 3213           </entry>
 3214           <entry colname="2">
 3215         <para>
 3216           Includes a file.
 3217         </para>
 3218           </entry>
 3219         </row>
 3220         <row rowsep="0">
 3221           <entry colname="1">
 3222         <para><command>key</command></para>
 3223           </entry>
 3224           <entry colname="2">
 3225         <para>
 3226           Specifies key information for use in
 3227           authentication and authorization using TSIG.
 3228         </para>
 3229           </entry>
 3230         </row>
 3231         <row rowsep="0">
 3232           <entry colname="1">
 3233         <para><command>logging</command></para>
 3234           </entry>
 3235           <entry colname="2">
 3236         <para>
 3237           Specifies what information the server logs and where
 3238           the log messages are sent.
 3239         </para>
 3240           </entry>
 3241         </row>
 3242         <row rowsep="0">
 3243           <entry colname="1">
 3244         <para><command>lwres</command></para>
 3245           </entry>
 3246           <entry colname="2">
 3247         <para>
 3248           Configures <command>named</command> to
 3249           also act as a lightweight resolver daemon (<command>lwresd</command>).
 3250         </para>
 3251           </entry>
 3252         </row>
 3253         <row rowsep="0">
 3254           <entry colname="1">
 3255         <para><command>masters</command></para>
 3256           </entry>
 3257           <entry colname="2">
 3258         <para>
 3259           Defines a named list of primary servers for
 3260           inclusion in stub and secondary zones'
 3261           <command>masters</command> or
 3262           <command>also-notify</command> lists.
 3263         </para>
 3264           </entry>
 3265         </row>
 3266         <row rowsep="0">
 3267           <entry colname="1">
 3268         <para><command>options</command></para>
 3269           </entry>
 3270           <entry colname="2">
 3271         <para>
 3272           Controls global server configuration
 3273           options and sets defaults for other statements.
 3274         </para>
 3275           </entry>
 3276         </row>
 3277         <row rowsep="0">
 3278           <entry colname="1">
 3279         <para><command>server</command></para>
 3280           </entry>
 3281           <entry colname="2">
 3282         <para>
 3283           Sets certain configuration options on
 3284           a per-server basis.
 3285         </para>
 3286           </entry>
 3287         </row>
 3288         <row rowsep="0">
 3289           <entry colname="1">
 3290         <para><command>statistics-channels</command></para>
 3291           </entry>
 3292           <entry colname="2">
 3293         <para>
 3294           Declares communication channels to get access to
 3295           <command>named</command> statistics.
 3296         </para>
 3297           </entry>
 3298         </row>
 3299         <row rowsep="0">
 3300           <entry colname="1">
 3301         <para><command>trusted-keys</command></para>
 3302           </entry>
 3303           <entry colname="2">
 3304         <para>
 3305           Defines trusted DNSSEC keys.
 3306         </para>
 3307           </entry>
 3308         </row>
 3309         <row rowsep="0">
 3310           <entry colname="1">
 3311         <para><command>managed-keys</command></para>
 3312           </entry>
 3313           <entry colname="2">
 3314         <para>
 3315           Lists DNSSEC keys to be kept up-to-date
 3316           using RFC 5011 trust anchor maintenance.
 3317         </para>
 3318           </entry>
 3319         </row>
 3320         <row rowsep="0">
 3321           <entry colname="1">
 3322         <para><command>view</command></para>
 3323           </entry>
 3324           <entry colname="2">
 3325         <para>
 3326           Defines a view.
 3327         </para>
 3328           </entry>
 3329         </row>
 3330         <row rowsep="0">
 3331           <entry colname="1">
 3332         <para><command>zone</command></para>
 3333           </entry>
 3334           <entry colname="2">
 3335         <para>
 3336           Defines a zone.
 3337         </para>
 3338           </entry>
 3339         </row>
 3340       </tbody>
 3341     </tgroup>
 3342       </informaltable>
 3343 
 3344       <para>
 3345     The <command>logging</command> and
 3346     <command>options</command> statements may only occur once
 3347     per
 3348     configuration.
 3349       </para>
 3350 
 3351       <section xml:id="acl_grammar"><info><title><command>acl</command> Statement Grammar</title></info>
 3352     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="acl.grammar.xml"/>
 3353       </section>
 3354       <section xml:id="acl"><info><title><command>acl</command> Statement Definition and
 3355       Usage</title></info>
 3356 
 3357     <para>
 3358       The <command>acl</command> statement assigns a symbolic
 3359       name to an address match list. It gets its name from one of the primary
 3360       uses of address match lists: Access Control Lists (ACLs).
 3361     </para>
 3362 
 3363     <para>
 3364       The following ACLs are built-in:
 3365     </para>
 3366 
 3367     <informaltable colsep="0" rowsep="0">
 3368       <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table">
 3369         <colspec colname="1" colnum="1" colsep="0" colwidth="1.130in"/>
 3370         <colspec colname="2" colnum="2" colsep="0" colwidth="4.000in"/>
 3371         <tbody>
 3372           <row rowsep="0">
 3373         <entry colname="1">
 3374           <para><command>any</command></para>
 3375         </entry>
 3376         <entry colname="2">
 3377           <para>
 3378             Matches all hosts.
 3379           </para>
 3380         </entry>
 3381           </row>
 3382           <row rowsep="0">
 3383         <entry colname="1">
 3384           <para><command>none</command></para>
 3385         </entry>
 3386         <entry colname="2">
 3387           <para>
 3388             Matches no hosts.
 3389           </para>
 3390         </entry>
 3391           </row>
 3392           <row rowsep="0">
 3393         <entry colname="1">
 3394           <para><command>localhost</command></para>
 3395         </entry>
 3396         <entry colname="2">
 3397           <para>
 3398             Matches the IPv4 and IPv6 addresses of all network
 3399             interfaces on the system.  When addresses are
 3400             added or removed, the <command>localhost</command>
 3401             ACL element is updated to reflect the changes.
 3402           </para>
 3403         </entry>
 3404           </row>
 3405           <row rowsep="0">
 3406         <entry colname="1">
 3407           <para><command>localnets</command></para>
 3408         </entry>
 3409         <entry colname="2">
 3410           <para>
 3411             Matches any host on an IPv4 or IPv6 network
 3412             for which the system has an interface.
 3413             When addresses are added or removed,
 3414             the <command>localnets</command>
 3415             ACL element is updated to reflect the changes.
 3416             Some systems do not provide a way to determine the prefix
 3417             lengths of
 3418             local IPv6 addresses;
 3419             in such cases, <command>localnets</command>
 3420             only matches the local
 3421             IPv6 addresses, just like <command>localhost</command>.
 3422           </para>
 3423         </entry>
 3424           </row>
 3425         </tbody>
 3426       </tgroup>
 3427     </informaltable>
 3428       </section>
 3429       <section xml:id="controls_grammar"><info><title><command>controls</command> Statement Grammar</title></info>
 3430     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="controls.grammar.xml"/>
 3431       </section>
 3432 
 3433       <section xml:id="controls_statement_definition_and_usage"><info><title><command>controls</command> Statement Definition and
 3434       Usage</title></info>
 3435 
 3436     <para>
 3437       The <command>controls</command> statement declares control
 3438       channels to be used by system administrators to manage the
 3439       operation of the name server. These control channels are
 3440       used by the <command>rndc</command> utility to send
 3441       commands to and retrieve non-DNS results from a name server.
 3442     </para>
 3443 
 3444     <para>
 3445       An <command>inet</command> control channel is a TCP socket
 3446       listening at the specified <command>ip_port</command> on the
 3447       specified <command>ip_addr</command>, which can be an IPv4 or IPv6
 3448       address.  An <command>ip_addr</command> of <literal>*</literal> (asterisk) is
 3449       interpreted as the IPv4 wildcard address; connections are
 3450       accepted on any of the system's IPv4 addresses.
 3451       To listen on the IPv6 wildcard address,
 3452       use an <command>ip_addr</command> of <literal>::</literal>.
 3453       If <command>rndc</command> is only used on the local host,
 3454       using the loopback address (<literal>127.0.0.1</literal>
 3455       or <literal>::1</literal>) is recommended for maximum security.
 3456     </para>
 3457 
 3458     <para>
 3459       If no port is specified, port 953 is used. The asterisk
 3460       "<literal>*</literal>" cannot be used for <command>ip_port</command>.
 3461     </para>
 3462 
 3463     <para>
 3464       The ability to issue commands over the control channel is
 3465       restricted by the <command>allow</command> and
 3466       <command>keys</command> clauses.
 3467       Connections to the control channel are permitted based on the
 3468       <command>address_match_list</command>.  This is for simple
 3469       IP address-based filtering only; any <command>key_id</command>
 3470       elements of the <command>address_match_list</command>
 3471       are ignored.
 3472     </para>
 3473 
 3474     <para>
 3475       A <command>unix</command> control channel is a Unix domain
 3476       socket listening at the specified path in the file system.
 3477       Access to the socket is specified by the <command>perm</command>,
 3478       <command>owner</command>, and <command>group</command> clauses.
 3479       Note on some platforms (SunOS and Solaris), the permissions
 3480       (<command>perm</command>) are applied to the parent directory
 3481       as the permissions on the socket itself are ignored.
 3482     </para>
 3483 
 3484     <para>
 3485       The primary authorization mechanism of the command
 3486       channel is the <command>key_list</command>, which
 3487       contains a list of <command>key_id</command>s.
 3488       Each <command>key_id</command> in the <command>key_list</command>
 3489       is authorized to execute commands over the control channel.
 3490       See <xref linkend="rndc"/> in <xref linkend="admin_tools"/>)
 3491       for information about configuring keys in <command>rndc</command>.
 3492     </para>
 3493 
 3494     <para>
 3495       If the <command>read-only</command> clause is enabled, the
 3496       control channel is limited to the following set of read-only
 3497       commands: <command>nta -dump</command>,
 3498       <command>null</command>, <command>status</command>,
 3499       <command>showzone</command>, <command>testgen</command>, and
 3500       <command>zonestatus</command>. By default,
 3501       <command>read-only</command> is not enabled and the control
 3502       channel allows read-write access.
 3503     </para>
 3504 
 3505     <para>
 3506       If no <command>controls</command> statement is present,
 3507       <command>named</command> sets up a default
 3508       control channel listening on the loopback address 127.0.0.1
 3509       and its IPv6 counterpart ::1.
 3510       In this case, and also when the <command>controls</command> statement
 3511       is present but does not have a <command>keys</command> clause,
 3512       <command>named</command> attempts to load the command channel key
 3513       from the file <filename>rndc.key</filename> in
 3514       <filename>/etc</filename> (or whatever <varname>sysconfdir</varname>
 3515       was specified when <acronym>BIND</acronym> was built).
 3516       To create an <filename>rndc.key</filename> file, run
 3517       <userinput>rndc-confgen -a</userinput>.
 3518     </para>
 3519 
 3520     <para>
 3521       The key name and the size of the secret cannot be easily changed; if it
 3522       is desirable to change those things, make a
 3523       <filename>rndc.conf</filename> with a custom key.  The <filename>rndc.key</filename> file
 3524       also has its
 3525       permissions set such that only the owner of the file (the user that
 3526       <command>named</command> is running as) can access it.
 3527       For greater flexibility in allowing other users to access
 3528       <command>rndc</command> commands, create
 3529       a
 3530       <filename>rndc.conf</filename> file and make it group-readable by a group
 3531       that contains the users who should have access.
 3532     </para>
 3533 
 3534     <para>
 3535       To disable the command channel, use an empty
 3536       <command>controls</command> statement:
 3537       <command>controls { };</command>.
 3538     </para>
 3539 
 3540       </section>
 3541       <section xml:id="include_grammar"><info><title><command>include</command> Statement Grammar</title></info>
 3542 
 3543     <programlisting><command>include</command> <replaceable>filename</replaceable><command>;</command></programlisting>
 3544       </section>
 3545       <section xml:id="include_statement"><info><title><command>include</command> Statement Definition and Usage</title></info>
 3546 
 3547     <para>
 3548       The <command>include</command> statement inserts the
 3549       specified file at the point where the <command>include</command>
 3550       statement is encountered. The <command>include</command>
 3551         statement facilitates the administration of configuration
 3552       files
 3553       by permitting the reading or writing of some things but not
 3554       others. For example, the statement could include private keys
 3555       that are readable only by the name server.
 3556     </para>
 3557 
 3558       </section>
 3559       <section xml:id="key_grammar"><info><title><command>key</command> Statement Grammar</title></info>
 3560     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="key.grammar.xml"/>
 3561       </section>
 3562 
 3563       <section xml:id="key_statement"><info><title><command>key</command> Statement Definition and Usage</title></info>
 3564 
 3565     <para>
 3566       The <command>key</command> statement defines a shared
 3567       secret key for use with TSIG (see <xref linkend="tsig"/>)
 3568       or the command channel
 3569       (see <xref linkend="controls_statement_definition_and_usage"/>).
 3570     </para>
 3571 
 3572     <para>
 3573       The <command>key</command> statement can occur at the
 3574       top level
 3575       of the configuration file or inside a <command>view</command>
 3576       statement.  Keys defined in top-level <command>key</command>
 3577       statements can be used in all views.  Keys intended for use in
 3578       a <command>controls</command> statement
 3579       (see <xref linkend="controls_statement_definition_and_usage"/>)
 3580       must be defined at the top level.
 3581     </para>
 3582 
 3583     <para>
 3584       The <replaceable>key_id</replaceable>, also known as the
 3585       key name, is a domain name that uniquely identifies the key. It can
 3586       be used in a <command>server</command>
 3587       statement to cause requests sent to that
 3588       server to be signed with this key, or in address match lists to
 3589       verify that incoming requests have been signed with a key
 3590       matching this name, algorithm, and secret.
 3591     </para>
 3592 
 3593     <para>
 3594       The <replaceable>algorithm_id</replaceable> is a string
 3595       that specifies a security/authentication algorithm.  The
 3596       <command>named</command> server supports <literal>hmac-md5</literal>,
 3597       <literal>hmac-sha1</literal>, <literal>hmac-sha224</literal>,
 3598       <literal>hmac-sha256</literal>, <literal>hmac-sha384</literal>,
 3599       and <literal>hmac-sha512</literal> TSIG authentication.
 3600       Truncated hashes are supported by appending the minimum
 3601       number of required bits preceded by a dash, e.g.,
 3602       <literal>hmac-sha1-80</literal>.  The
 3603       <replaceable>secret_string</replaceable> is the secret
 3604       to be used by the algorithm, and is treated as a Base64-encoded string.
 3605     </para>
 3606 
 3607       </section>
 3608       <section xml:id="logging_grammar"><info><title><command>logging</command> Statement Grammar</title></info>
 3609     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.grammar.xml"/>
 3610       </section>
 3611 
 3612       <section xml:id="logging_statement"><info><title><command>logging</command> Statement Definition and Usage</title></info>
 3613 
 3614     <para>
 3615       The <command>logging</command> statement configures a
 3616       wide
 3617       variety of logging options for the name server. Its <command>channel</command> phrase
 3618       associates output methods, format options, and severity levels with
 3619       a name that can then be used with the <command>category</command> phrase
 3620       to select how various classes of messages are logged.
 3621     </para>
 3622     <para>
 3623       Only one <command>logging</command> statement is used to
 3624       define
 3625       as many channels and categories as desired. If there is no <command>logging</command> statement,
 3626       the logging configuration is:
 3627     </para>
 3628 
 3629 <programlisting>logging {
 3630      category default { default_syslog; default_debug; };
 3631      category unmatched { null; };
 3632 };
 3633 </programlisting>
 3634 
 3635     <para>
 3636       If <command>named</command> is started with the
 3637       <option>-L</option> option, it logs to the specified file
 3638       at startup, instead of using syslog. In this case the logging
 3639       configuration is:
 3640     </para>
 3641 
 3642 <programlisting>logging {
 3643      category default { default_logfile; default_debug; };
 3644      category unmatched { null; };
 3645 };
 3646 </programlisting>
 3647 
 3648     <para>
 3649       The logging configuration
 3650       is only established when
 3651       the entire configuration file has been parsed. When the server starts up, all logging messages
 3652       regarding syntax errors in the configuration file go to the default
 3653       channels, or to standard error if the <option>-g</option> option
 3654       was specified.
 3655     </para>
 3656 
 3657     <section xml:id="channel"><info><title>The <command>channel</command> Phrase</title></info>
 3658 
 3659       <para>
 3660         All log output goes to one or more <emphasis>channels</emphasis>;
 3661         there is no limit to the number of channels that can be created.
 3662       </para>
 3663 
 3664       <para>
 3665         Every channel definition must include a destination clause that
 3666         says whether messages selected for the channel go to a file, go to a
 3667         particular syslog facility, go to the standard error stream, or are
 3668         discarded. The definition can optionally also limit the message severity level
 3669         that is accepted by the channel (the default is
 3670         <command>info</command>), and whether to include a
 3671         <command>named</command>-generated time stamp, the
 3672         category name,
 3673         and/or the severity level (the default is not to include any).
 3674       </para>
 3675 
 3676       <para>
 3677         The <command>null</command> destination clause
 3678         causes all messages sent to the channel to be discarded;
 3679         in that case, other options for the channel are meaningless.
 3680       </para>
 3681 
 3682       <para>
 3683         The <command>file</command> destination clause directs
 3684         the channel
 3685         to a disk file.  It can include limitations
 3686         both on how large the file is allowed to become, and on how many
 3687         versions
 3688         of the file are saved each time the file is opened.
 3689       </para>
 3690 
 3691       <para>
 3692         If the <command>versions</command> log file
 3693         option is used, then
 3694         <command>named</command> retains that many backup
 3695         versions of the file by
 3696         renaming them when opening.  For example, to keep
 3697         three old versions
 3698         of the file <filename>lamers.log</filename>, just
 3699         before it is opened
 3700         <filename>lamers.log.1</filename> is renamed to
 3701         <filename>lamers.log.2</filename>, <filename>lamers.log.0</filename> is renamed
 3702         to <filename>lamers.log.1</filename>, and <filename>lamers.log</filename> is
 3703         renamed to <filename>lamers.log.0</filename>.
 3704         The <command>versions unlimited</command> option can be set to
 3705         not limit
 3706         the number of versions.
 3707         If a <command>size</command> option is associated with
 3708         the log file,
 3709         then renaming is only done when the file being opened exceeds the
 3710         indicated size.  No backup versions are kept by default; any
 3711         existing
 3712         log file is simply appended.
 3713       </para>
 3714 
 3715       <para>
 3716         The <command>size</command> option for files is used
 3717         to limit log
 3718         growth. If the file ever exceeds the size, then <command>named</command>
 3719         stops writing to the file unless it also has a <command>versions</command> option
 3720         associated with it.  If backup versions are kept, the files are
 3721         rolled as
 3722         described above and a new one begun.  If there is no
 3723         <command>versions</command> option, no more data is
 3724         written to the log
 3725         until some out-of-band mechanism removes or truncates the log to
 3726         less than the
 3727         maximum size.  The default behavior is not to limit the size of
 3728         the
 3729         file.
 3730       </para>
 3731 
 3732       <para>
 3733         Here is an example using the <command>size</command> and
 3734         <command>versions</command> options:
 3735       </para>
 3736 
 3737 <programlisting>channel an_example_channel {
 3738     file "example.log" versions 3 size 20m;
 3739     print-time yes;
 3740     print-category yes;
 3741 };
 3742 </programlisting>
 3743 
 3744       <para>
 3745         The <command>syslog</command> destination clause
 3746         directs the
 3747         channel to the system log.  Its argument is a
 3748         syslog facility as described in the <command>syslog</command> man
 3749         page. Known facilities are <command>kern</command>, <command>user</command>,
 3750         <command>mail</command>, <command>daemon</command>, <command>auth</command>,
 3751         <command>syslog</command>, <command>lpr</command>, <command>news</command>,
 3752         <command>uucp</command>, <command>cron</command>, <command>authpriv</command>,
 3753         <command>ftp</command>, <command>local0</command>, <command>local1</command>,
 3754         <command>local2</command>, <command>local3</command>, <command>local4</command>,
 3755         <command>local5</command>, <command>local6</command>, and
 3756         <command>local7</command>; however, not all facilities
 3757         are supported on
 3758         all operating systems.
 3759         How <command>syslog</command> handles messages
 3760         sent to
 3761         this facility is described in the <command>syslog.conf</command> man
 3762         page. On a system which uses a very old version of <command>syslog</command>, which
 3763         only uses two arguments to the <command>openlog()</command> function,
 3764         then this clause is silently ignored.
 3765       </para>
 3766       <para>
 3767         On Windows machines, syslog messages are directed to the EventViewer.
 3768       </para>
 3769       <para>
 3770         The <command>severity</command> clause works like <command>syslog</command>'s
 3771         "priorities," except that they can also be used when writing
 3772         straight to a file rather than using <command>syslog</command>.
 3773         Messages which are not at least of the severity level given are
 3774         not selected for the channel; messages of higher severity
 3775         levels
 3776         are accepted.
 3777       </para>
 3778       <para>
 3779         When using <command>syslog</command>, the <command>syslog.conf</command> priorities
 3780         also determine what eventually passes through. For example,
 3781         defining a channel facility and severity as <command>daemon</command> and <command>debug</command>, but
 3782         only logging <command>daemon.warning</command> via <command>syslog.conf</command>,
 3783         causes messages of severity <command>info</command> and
 3784         <command>notice</command> to
 3785         be dropped. If the situation were reversed, with <command>named</command> writing
 3786         messages of only <command>warning</command> or higher,
 3787         then <command>syslogd</command> would
 3788         print all messages it received from the channel.
 3789       </para>
 3790 
 3791       <para>
 3792         The <command>stderr</command> destination clause
 3793         directs the
 3794         channel to the server's standard error stream.  This is intended
 3795         for
 3796         use when the server is running as a foreground process, as
 3797         when debugging a configuration, for example.
 3798       </para>
 3799 
 3800       <para>
 3801         The server can supply extensive debugging information when
 3802         it is in debugging mode. If the server's global debug level is
 3803         greater
 3804         than zero, debugging mode is active. The global debug
 3805         level is set either by starting the <command>named</command> server
 3806         with the <option>-d</option> flag followed by a positive integer,
 3807         or by running <command>rndc trace</command>.
 3808         The global debug level
 3809         can be set to zero, and debugging mode turned off, by running <command>rndc
 3810         notrace</command>. All debugging messages in the server have a debug
 3811         level; higher debug levels give more detailed output. Channels
 3812         that specify a specific debug severity, for example:
 3813       </para>
 3814 
 3815 <programlisting>channel specific_debug_level {
 3816     file "foo";
 3817     severity debug 3;
 3818 };
 3819 </programlisting>
 3820 
 3821       <para>
 3822         get debugging output of level 3 or less any time the
 3823         server is in debugging mode, regardless of the global debugging
 3824         level. Channels with <command>dynamic</command>
 3825         severity use the
 3826         server's global debug level to determine what messages to print.
 3827       </para>
 3828       <para>
 3829         If <command>print-time</command> is set to
 3830         <userinput>yes</userinput>, then the date and time are logged.
 3831         <command>print-time</command> may be specified for a
 3832         <command>syslog</command> channel, but is usually
 3833         unnecessary since <command>syslog</command> also logs
 3834         the date and time. If <command>print-category</command> is
 3835         set to <userinput>yes</userinput>, then the
 3836         category of the message is logged as well. Finally, if
 3837         <command>print-severity</command> is set, then the severity
 3838         level of the message is logged.
 3839         The <command>print-</command> options may
 3840         be used in any combination, and are always printed in the
 3841         following
 3842         order: time, category, severity. Here is an example where all
 3843         three <command>print-</command> options
 3844         are on:
 3845       </para>
 3846 
 3847       <para>
 3848         <computeroutput>28-Feb-2000 15:05:32.863 general: notice: running</computeroutput>
 3849       </para>
 3850 
 3851       <para>
 3852         If <command>buffered</command> has been turned on, the output
 3853         to files is not flushed after each log entry.  By default
 3854         all log messages are flushed.
 3855       </para>
 3856 
 3857       <para>
 3858         There are four predefined channels that are used for
 3859         <command>named</command>'s default logging, as follows.
 3860         If <command>named</command> is started with the
 3861         <option>-L</option>, then a
 3862         fifth channel, <command>default_logfile</command>, is added.
 3863         How they are
 3864         used is described in <xref linkend="the_category_phrase"/>.
 3865       </para>
 3866 
 3867 <programlisting>channel default_syslog {
 3868     // send to syslog's daemon facility
 3869     syslog daemon;
 3870     // only send priority info and higher
 3871     severity info;
 3872 };
 3873 
 3874 channel default_debug {
 3875     // write to named.run in the working directory
 3876     // Note: stderr is used instead of "named.run" if
 3877     // the server is started with the '-g' option.
 3878     file "named.run";
 3879     // log at the server's current debug level
 3880     severity dynamic;
 3881 };
 3882 
 3883 channel default_stderr {
 3884     // writes to stderr
 3885     stderr;
 3886     // only send priority info and higher
 3887     severity info;
 3888 };
 3889 
 3890 channel null {
 3891    // toss anything sent to this channel
 3892    null;
 3893 };
 3894 
 3895 channel default_logfile {
 3896     // this channel is only present if named is
 3897     // started with the -L option, whose argument
 3898     // provides the file name
 3899     file "...";
 3900     // log at the server's current debug level
 3901     severity dynamic;
 3902 };
 3903 </programlisting>
 3904 
 3905       <para>
 3906         The <command>default_debug</command> channel has the
 3907         special
 3908         property that it only produces output when the server's debug
 3909         level is
 3910         non-zero.  It normally writes to a file called <filename>named.run</filename>
 3911         in the server's working directory.
 3912       </para>
 3913 
 3914       <para>
 3915         For security reasons, when the <option>-u</option>
 3916         command-line option is used, the <filename>named.run</filename> file
 3917         is created only after <command>named</command> has
 3918         changed to the
 3919         new UID, and any debug output generated while <command>named</command> is
 3920         starting - and still running as root - is discarded.
 3921         To capture this output, run the server with the <option>-L</option>
 3922         option to specify a default logfile, or the <option>-g</option>
 3923         option to log to standard error which can be redirected to a file.
 3924       </para>
 3925 
 3926       <para>
 3927         Once a channel is defined, it cannot be redefined.
 3928         The built-in channels cannot be altered directly, but
 3929         the default logging can be modified by pointing categories at defined channels.
 3930       </para>
 3931     </section>
 3932 
 3933     <section xml:id="the_category_phrase"><info><title>The <command>category</command> Phrase</title></info>
 3934 
 3935       <para>
 3936         There are many categories, so desired logs
 3937         can be sent anywhere while unwanted logs are ignored. If
 3938         a list of channels is not specified for a category, log
 3939         messages
 3940         in that category are sent to the <command>default</command> category
 3941         instead. If no default category is specified, the following
 3942         "default default" is used:
 3943       </para>
 3944 
 3945 <programlisting>category default { default_syslog; default_debug; };
 3946 </programlisting>
 3947 
 3948       <para>
 3949         If <command>named</command> is started with the
 3950         <option>-L</option> option, the default category is:
 3951       </para>
 3952 
 3953 <programlisting>category default { default_logfile; default_debug; };
 3954 </programlisting>
 3955 
 3956       <para>
 3957         As an example, let's say a user wants to log security events to
 3958         a file, but also wants to keep the default logging behavior. They would
 3959         specify the following:
 3960       </para>
 3961 
 3962 <programlisting>channel my_security_channel {
 3963     file "my_security_file";
 3964     severity info;
 3965 };
 3966 category security {
 3967     my_security_channel;
 3968     default_syslog;
 3969     default_debug;
 3970 };</programlisting>
 3971 
 3972       <para>
 3973         To discard all messages in a category, specify the <command>null</command> channel:
 3974       </para>
 3975 
 3976 <programlisting>category xfer-out { null; };
 3977 category notify { null; };
 3978 </programlisting>
 3979 
 3980       <para>
 3981         The following are the available categories and brief descriptions
 3982         of the types of log information they contain. More
 3983         categories may be added in future <acronym>BIND</acronym> releases.
 3984       </para>
 3985       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging-categories.xml"/>
 3986     </section>
 3987     <section xml:id="query_errors"><info><title>The <command>query-errors</command> Category</title></info>
 3988       <para>
 3989         The <command>query-errors</command> category is
 3990         used to indicate why and how specific queries resulted in
 3991         responses which indicate an error.  Normally, these messages
 3992         will be logged at <command>debug</command> logging levels;
 3993         note, however, that if query logging is active, some are
 3994         logged at <command>info</command>. The logging levels are
 3995         described below:
 3996       </para>
 3997 
 3998       <para>
 3999         At <command>debug</command> level 1 or higher - or at
 4000         <command>info</command>, when query logging is active - each
 4001         response with response code SERVFAIL is logged as follows:
 4002       </para>
 4003       <para>
 4004         <computeroutput>client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</computeroutput>
 4005       </para>
 4006       <para>
 4007         This means an error resulting in SERVFAIL was detected at line
 4008         3880 of source file <filename>query.c</filename>.  Log messages
 4009         of this level are particularly helpful in identifying the cause of
 4010         SERVFAIL for an authoritative server.
 4011       </para>
 4012       <para>
 4013         At <command>debug</command> level 2 or higher, detailed
 4014         context information about recursive resolutions that resulted in
 4015         SERVFAIL is logged.  The log message looks like this:
 4016       </para>
 4017       <para>
 4018 <!-- NOTE: newlines and some spaces added so this would fit on page -->
 4019         <programlisting>
 4020 fetch completed at resolver.c:2970 for www.example.com/A
 4021 in 10.000183: timed out/success [domain:example.com,
 4022 referral:2,restart:7,qrysent:8,timeout:5,lame:0,quota:0,neterr:0,
 4023 badresp:1,adberr:0,findfail:0,valfail:0]
 4024         </programlisting>
 4025       </para>
 4026       <para>
 4027         The first part before the colon shows that a recursive
 4028         resolution for AAAA records of www.example.com completed
 4029         in 10.000183 seconds, and the final result that led to the
 4030         SERVFAIL was determined at line 2970 of source file
 4031         <filename>resolver.c</filename>.
 4032       </para>
 4033       <para>
 4034         The next part shows the detected final result and the
 4035         latest result of DNSSEC validation.  The latter is always
 4036         "success" when no validation attempt was made.  In this example,
 4037         this query probably resulted in SERVFAIL because all name
 4038         servers are down or unreachable, leading to a timeout in 10
 4039         seconds.  DNSSEC validation was probably not attempted.
 4040       </para>
 4041       <para>
 4042         The last part, enclosed in square brackets, shows statistics
 4043         collected for this particular resolution attempt.
 4044         The <varname>domain</varname> field shows the deepest zone that
 4045         the resolver reached; it is the zone where the error was
 4046         finally detected.  The meaning of the other fields is
 4047         summarized in the following table.
 4048       </para>
 4049 
 4050       <informaltable colsep="0" rowsep="0">
 4051         <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 4052           <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/>
 4053           <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/>
 4054           <tbody>
 4055         <row rowsep="0">
 4056           <entry colname="1">
 4057             <para><varname>referral</varname></para>
 4058           </entry>
 4059           <entry colname="2">
 4060             <para>
 4061               The number of referrals the resolver received
 4062               throughout the resolution process.
 4063               In the above example there are two, which are most
 4064               likely com and example.com.
 4065             </para>
 4066           </entry>
 4067         </row>
 4068         <row rowsep="0">
 4069           <entry colname="1">
 4070             <para><varname>restart</varname></para>
 4071           </entry>
 4072           <entry colname="2">
 4073             <para>
 4074               The number of cycles that the resolver tried
 4075               remote servers at the <varname>domain</varname>
 4076               zone.
 4077               In each cycle, the resolver sends one query
 4078               (possibly resending it, depending on the response)
 4079               to each known name server of
 4080               the <varname>domain</varname> zone.
 4081             </para>
 4082           </entry>
 4083         </row>
 4084         <row rowsep="0">
 4085           <entry colname="1">
 4086             <para><varname>qrysent</varname></para>
 4087           </entry>
 4088           <entry colname="2">
 4089             <para>
 4090               The number of queries the resolver sent at the
 4091               <varname>domain</varname> zone.
 4092             </para>
 4093           </entry>
 4094         </row>
 4095         <row rowsep="0">
 4096           <entry colname="1">
 4097             <para><varname>timeout</varname></para>
 4098           </entry>
 4099           <entry colname="2">
 4100             <para>
 4101               The number of timeouts since the resolver
 4102               received the last response.
 4103             </para>
 4104           </entry>
 4105         </row>
 4106         <row rowsep="0">
 4107           <entry colname="1">
 4108             <para><varname>lame</varname></para>
 4109           </entry>
 4110           <entry colname="2">
 4111             <para>
 4112               The number of lame servers the resolver detected
 4113               at the <varname>domain</varname> zone.
 4114               A server is detected to be lame either by an
 4115               invalid response or as a result of lookup in
 4116               BIND 9's address database (ADB), where lame
 4117               servers are cached.
 4118             </para>
 4119           </entry>
 4120         </row>
 4121         <row rowsep="0">
 4122           <entry colname="1">
 4123             <para><varname>quota</varname></para>
 4124           </entry>
 4125           <entry colname="2">
 4126             <para>
 4127               The number of times the resolver was unable
 4128               to send a query because it had exceeded the
 4129               permissible fetch quota for a server.
 4130             </para>
 4131           </entry>
 4132         </row>
 4133         <row rowsep="0">
 4134           <entry colname="1">
 4135             <para><varname>neterr</varname></para>
 4136           </entry>
 4137           <entry colname="2">
 4138             <para>
 4139               The number of erroneous results that the
 4140               resolver encountered in sending queries
 4141               at the <varname>domain</varname> zone.
 4142               One common case is when the remote server is
 4143               unreachable and the resolver receives an "ICMP
 4144               unreachable" error message.
 4145             </para>
 4146           </entry>
 4147         </row>
 4148         <row rowsep="0">
 4149           <entry colname="1">
 4150             <para><varname>badresp</varname></para>
 4151           </entry>
 4152           <entry colname="2">
 4153             <para>
 4154               The number of unexpected responses (other than
 4155               <varname>lame</varname>) to queries sent by the
 4156               resolver at the <varname>domain</varname> zone.
 4157             </para>
 4158           </entry>
 4159         </row>
 4160         <row rowsep="0">
 4161           <entry colname="1">
 4162             <para><varname>adberr</varname></para>
 4163           </entry>
 4164           <entry colname="2">
 4165             <para>
 4166               Failures in finding remote server addresses
 4167               of the <varname>domain</varname> zone in the ADB.
 4168               One common case of this is that the remote
 4169               server's name does not have any address records.
 4170             </para>
 4171           </entry>
 4172         </row>
 4173         <row rowsep="0">
 4174           <entry colname="1">
 4175             <para><varname>findfail</varname></para>
 4176           </entry>
 4177           <entry colname="2">
 4178             <para>
 4179               Failures to resolve remote server addresses.
 4180               This is a total number of failures throughout
 4181               the resolution process.
 4182             </para>
 4183           </entry>
 4184         </row>
 4185         <row rowsep="0">
 4186           <entry colname="1">
 4187             <para><varname>valfail</varname></para>
 4188           </entry>
 4189           <entry colname="2">
 4190             <para>
 4191               Failures of DNSSEC validation.
 4192               Validation failures are counted throughout
 4193               the resolution process (not limited to
 4194               the <varname>domain</varname> zone), but should
 4195               only happen in <varname>domain</varname>.
 4196             </para>
 4197           </entry>
 4198         </row>
 4199           </tbody>
 4200         </tgroup>
 4201       </informaltable>
 4202       <para>
 4203         At <command>debug</command> level 3 or higher, the same
 4204         messages as those at <command>debug</command> level 1 are
 4205         logged for errors other than SERVFAIL. Note that negative
 4206         responses such as NXDOMAIN are not errors, and are not logged
 4207         at this debug level.
 4208       </para>
 4209       <para>
 4210         At <command>debug</command> level 4 or higher, the
 4211         detailed context information logged at <command>debug</command>
 4212         level 2 is logged for errors other than SERVFAIL and
 4213         for negative responses such as NXDOMAIN.
 4214       </para>
 4215     </section>
 4216       </section>
 4217 
 4218       <section xml:id="lwres_grammar"><info><title><command>lwres</command> Statement Grammar</title></info>
 4219 
 4220     <para>
 4221        This is the grammar of the <command>lwres</command>
 4222       statement in the <filename>named.conf</filename> file:
 4223     </para>
 4224 
 4225 <programlisting><command>lwres {</command>
 4226   [ <command>listen-on {</command>
 4227     ( <replaceable>ip_addr</replaceable> [ <command>port</command> <replaceable>ip_port</replaceable> ] [ <command>dscp</command> <replaceable>ip_dscp</replaceable> ] <command>;</command> )
 4228       ...
 4229     <command>};</command> ]
 4230   [ <command>view</command> <replaceable>view_name</replaceable><command>;</command> ]
 4231   [ <command>search {</command> <replaceable>domain_name</replaceable> <command>;</command> ... <command>};</command> ]
 4232   [ <command>ndots</command> <replaceable>number</replaceable><command>;</command> ]
 4233   [ <command>lwres-tasks</command> <replaceable>number</replaceable><command>;</command> ]
 4234   [ <command>lwres-clients</command> <replaceable>number</replaceable><command>;</command> ]
 4235 <command>};</command>
 4236 </programlisting>
 4237 
 4238       </section>
 4239       <section xml:id="lwres_statement"><info><title><command>lwres</command> Statement Definition and Usage</title></info>
 4240 
 4241     <para>
 4242       The <command>lwres</command> statement configures the
 4243       name
 4244       server to also act as a lightweight resolver server. (See
 4245       <xref linkend="lwresd"/>.)  There may be multiple
 4246       <command>lwres</command> statements configuring
 4247       lightweight resolver servers with different properties.
 4248     </para>
 4249 
 4250     <para>
 4251       The <command>listen-on</command> statement specifies a
 4252       list of
 4253       IPv4 addresses (and ports) that this instance of a lightweight
 4254       resolver daemon
 4255       should accept requests on.  If no port is specified, port 921 is
 4256       used.
 4257       If this statement is omitted, requests are accepted on
 4258       127.0.0.1,
 4259       port 921.
 4260     </para>
 4261 
 4262     <para>
 4263       The <command>view</command> statement binds this
 4264       instance of a
 4265       lightweight resolver daemon to a view in the DNS namespace, so that
 4266       the
 4267       response is constructed in the same manner as a normal DNS
 4268       query
 4269       matching this view.  If this statement is omitted, the default view
 4270       is
 4271       used; if there is no default view, an error is triggered.
 4272     </para>
 4273 
 4274     <para>
 4275       The <command>search</command> statement is equivalent to
 4276       the
 4277       <command>search</command> statement in
 4278       <filename>/etc/resolv.conf</filename>.  It provides a
 4279       list of domains
 4280       which are appended to relative names in queries.
 4281     </para>
 4282 
 4283     <para>
 4284       The <command>ndots</command> statement is equivalent to
 4285       the
 4286       <command>ndots</command> statement in
 4287       <filename>/etc/resolv.conf</filename>.  It indicates the
 4288       minimum
 4289       number of dots in a relative domain name that should result in an
 4290       exact-match lookup before search path elements are appended.
 4291     </para>
 4292     <para>
 4293       The <option>lwres-tasks</option> statement specifies the number
 4294       of worker threads the lightweight resolver dedicates to serving
 4295       clients.  By default, the number is the same as the number of CPUs on
 4296       the system; this can be overridden using the <option>-n</option>
 4297       command-line option when starting the server.
 4298     </para>
 4299     <para>
 4300       The <option>lwres-clients</option> statement specifies
 4301       the number of client objects per thread the lightweight
 4302       resolver should create to serve client queries.
 4303       By default, if the lightweight resolver runs as a part
 4304       of <command>named</command>, 256 client objects are
 4305       created for each task; if it runs as <command>lwresd</command>,
 4306       1024 client objects are created for each thread. The maximum
 4307       value is 32768; higher values are silently ignored and
 4308       the maximum is used instead.
 4309       Note that setting too high a value may overconsume
 4310       system resources.
 4311     </para>
 4312     <para>
 4313       The maximum number of client queries that the lightweight
 4314       resolver can handle at any one time equals
 4315       <option>lwres-tasks</option> times <option>lwres-clients</option>.
 4316     </para>
 4317       </section>
 4318       <section xml:id="masters_grammar"><info><title><command>masters</command> Statement Grammar</title></info>
 4319     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="masters.grammar.xml"/>
 4320       </section>
 4321 
 4322       <section xml:id="masters_statement"><info><title><command>masters</command> Statement Definition and
 4323       Usage</title></info>
 4324 
 4325     <para><command>masters</command>
 4326       lists allow for a common set of primaries to be easily used by
 4327       multiple stub and secondary zones in their <command>masters</command>
 4328       or <command>also-notify</command> lists.
 4329     </para>
 4330       </section>
 4331 
 4332       <section xml:id="options_grammar"><info><title><command>options</command> Statement Grammar</title></info>
 4333 
 4334     <para>
 4335       This is the grammar of the <command>options</command>
 4336       statement in the <filename>named.conf</filename> file:
 4337     </para>
 4338     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="options.grammar.xml"/>
 4339       </section>
 4340 
 4341       <section xml:id="options"><info><title><command>options</command> Statement Definition and
 4342       Usage</title></info>
 4343 
 4344     <para>
 4345       The <command>options</command> statement sets up global
 4346       options
 4347       to be used by <acronym>BIND</acronym>. This statement
 4348       may appear only
 4349       once in a configuration file. If there is no <command>options</command>
 4350       statement, an options block with each option set to its default is
 4351       used.
 4352     </para>
 4353 
 4354     <variablelist>
 4355 
 4356         <varlistentry>
 4357           <term><command>attach-cache</command></term>
 4358           <listitem>
 4359         <para>
 4360           This option allows multiple views to share a single cache
 4361           database.
 4362           Each view has its own cache database by default, but
 4363           if multiple views have the same operational policy
 4364           for name resolution and caching, those views can
 4365           share a single cache to save memory, and possibly
 4366           improve resolution efficiency, by using this option.
 4367         </para>
 4368 
 4369         <para>
 4370           The <command>attach-cache</command> option
 4371           may also be specified in <command>view</command>
 4372           statements, in which case it overrides the
 4373           global <command>attach-cache</command> option.
 4374         </para>
 4375 
 4376         <para>
 4377           The <replaceable>cache_name</replaceable> specifies
 4378           the cache to be shared.
 4379           When the <command>named</command> server configures
 4380           views which are supposed to share a cache, it
 4381           creates a cache with the specified name for the
 4382           first view of these sharing views.
 4383           The rest of the views simply refer to the
 4384           already-created cache.
 4385         </para>
 4386 
 4387         <para>
 4388           One common configuration to share a cache is to
 4389           allow all views to share a single cache.
 4390           This can be done by specifying
 4391           <command>attach-cache</command> as a global
 4392           option with an arbitrary name.
 4393         </para>
 4394 
 4395         <para>
 4396           Another possible operation is to allow a subset of
 4397           all views to share a cache while the others
 4398           retain their own caches.
 4399           For example, if there are three views A, B, and C,
 4400           and only A and B should share a cache, specify the
 4401           <command>attach-cache</command> option as a view of A (or
 4402           B)'s option, referring to the other view name:
 4403         </para>
 4404 
 4405 <programlisting>
 4406   view "A" {
 4407     // this view has its own cache
 4408     ...
 4409   };
 4410   view "B" {
 4411     // this view refers to A's cache
 4412     attach-cache "A";
 4413   };
 4414   view "C" {
 4415     // this view has its own cache
 4416     ...
 4417   };
 4418 </programlisting>
 4419 
 4420         <para>
 4421           Views that share a cache must have the same policy
 4422           on configurable parameters that may affect caching.
 4423           The current implementation requires the following
 4424           configurable options be consistent among these
 4425           views:
 4426           <command>check-names</command>,
 4427           <command>cleaning-interval</command>,
 4428           <command>dnssec-accept-expired</command>,
 4429           <command>dnssec-validation</command>,
 4430           <command>max-cache-ttl</command>,
 4431           <command>max-ncache-ttl</command>,
 4432           <command>max-cache-size</command>, and
 4433           <command>zero-no-soa-ttl</command>.
 4434         </para>
 4435 
 4436         <para>
 4437           Note that there may be other parameters that may
 4438           cause confusion if they are inconsistent for
 4439           different views that share a single cache.
 4440           For example, if these views define different sets of
 4441           forwarders that can return different answers for the
 4442           same question, sharing the answer does not make
 4443           sense or could even be harmful.
 4444           It is administrator's responsibility to ensure that
 4445           configuration differences in different views do
 4446           not cause disruption with a shared cache.
 4447         </para>
 4448           </listitem>
 4449 
 4450         </varlistentry>
 4451 
 4452       <varlistentry>
 4453         <term><command>directory</command></term>
 4454         <listitem>
 4455           <para>
 4456         This sets the working directory of the server.
 4457         Any non-absolute pathnames in the configuration file are
 4458         taken as relative to this directory. The default
 4459         location for most server output files
 4460         (e.g., <filename>named.run</filename>) is this directory.
 4461         If a directory is not specified, the working directory
 4462         defaults to "<filename>.</filename>", the directory from
 4463         which the server was started. The directory specified
 4464         should be an absolute path. It is
 4465         <emphasis>strongly recommended</emphasis>
 4466         that the directory be writable by the effective user
 4467         ID of the <command>named</command> process.
 4468           </para>
 4469         </listitem>
 4470       </varlistentry>
 4471 
 4472       <varlistentry>
 4473         <term><command>dnstap</command></term>
 4474         <listitem>
 4475           <para>
 4476         <command>dnstap</command> is a fast, flexible method
 4477         for capturing and logging DNS traffic. Developed by
 4478         Robert Edmonds at Farsight Security, Inc., and supported
 4479         by multiple DNS implementations, <command>dnstap</command>
 4480         uses
 4481         <command>libfstrm</command> (a lightweight high-speed
 4482         framing library, see
 4483         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/farsightsec/fstrm">https://github.com/farsightsec/fstrm</link>) to send
 4484         event payloads which are encoded using Protocol Buffers
 4485         (<command>libprotobuf-c</command>, a mechanism for
 4486         serializing structured data developed
 4487         by Google, Inc.; see
 4488         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://developers.google.com/protocol-buffers/">https://developers.google.com/protocol-buffers</link>).
 4489           </para>
 4490           <para>
 4491         To enable <command>dnstap</command> at compile time,
 4492         the <command>fstrm</command> and <command>protobuf-c</command>
 4493         libraries must be available, and <acronym>BIND</acronym> must be configured with
 4494         <option>--enable-dnstap</option>.
 4495           </para>
 4496           <para>
 4497         The <command>dnstap</command> option is a bracketed list
 4498         of message types to be logged. These may be set differently
 4499         for each view. Supported types are <literal>client</literal>,
 4500         <literal>auth</literal>, <literal>resolver</literal>, and
 4501         <literal>forwarder</literal>.  Specifying type
 4502         <literal>all</literal> causes all <command>dnstap</command>
 4503         messages to be logged, regardless of type.
 4504           </para>
 4505           <para>
 4506         Each type may take an additional argument to indicate whether
 4507         to log <literal>query</literal> messages or
 4508         <literal>response</literal> messages; if not specified,
 4509         both queries and responses are logged.
 4510           </para>
 4511           <para>
 4512         Example: To log all authoritative queries and responses,
 4513         recursive client responses, and upstream queries sent by
 4514         the resolver, use:
 4515 <programlisting>dnstap {
 4516   auth;
 4517   client response;
 4518   resolver query;
 4519 };
 4520 </programlisting>
 4521           </para>
 4522           <para>
 4523         Logged <command>dnstap</command> messages can be parsed
 4524         using the <command>dnstap-read</command> utility (see
 4525         <xref linkend="man.dnstap-read"/> for details).
 4526           </para>
 4527           <para>
 4528         For more information on <command>dnstap</command>, see
 4529         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://dnstap.info">http://dnstap.info</link>.
 4530           </para>
 4531           <para>
 4532         The fstrm library has a number of tunables that are exposed
 4533         in <filename>named.conf</filename>, and can be modified
 4534         if necessary to improve performance or prevent loss of data.
 4535         These are:
 4536           </para>
 4537           <itemizedlist>
 4538         <listitem>
 4539           <simpara>
 4540             <command>fstrm-set-buffer-hint</command>: The
 4541             threshold number of bytes to accumulate in the output
 4542             buffer before forcing a buffer flush. The minimum is
 4543             1024, the maximum is 65536, and the default is 8192.
 4544           </simpara>
 4545         </listitem>
 4546         <listitem>
 4547           <simpara>
 4548             <command>fstrm-set-flush-timeout</command>: The number
 4549             of seconds to allow unflushed data to remain in the
 4550             output buffer. The minimum is 1 second, the maximum is
 4551             600 seconds (10 minutes), and the default is 1 second.
 4552           </simpara>
 4553         </listitem>
 4554         <listitem>
 4555           <simpara>
 4556             <command>fstrm-set-output-notify-threshold</command>:
 4557             The number of outstanding queue entries to allow on
 4558             an input queue before waking the I/O thread.
 4559             The minimum is 1 and the default is 32.
 4560           </simpara>
 4561         </listitem>
 4562         <listitem>
 4563           <simpara>
 4564             <command>fstrm-set-output-queue-model</command>:
 4565             The queuing semantics to use for queue
 4566             objects. The default is <literal>mpsc</literal>
 4567             (multiple producer, single consumer); the other
 4568             option is <literal>spsc</literal> (single producer,
 4569             single consumer).
 4570           </simpara>
 4571         </listitem>
 4572         <listitem>
 4573           <simpara>
 4574             <command>fstrm-set-input-queue-size</command>: The
 4575             number of queue entries to allocate for each
 4576             input queue. This value must be a power of 2.
 4577             The minimum is 2, the maximum is 16384, and
 4578             the default is 512.
 4579           </simpara>
 4580         </listitem>
 4581         <listitem>
 4582           <simpara>
 4583             <command>fstrm-set-output-queue-size</command>:
 4584             The number of queue entries to allocate for each
 4585             output queue. The minimum is 2, the maximum is
 4586             system-dependent and based on <option>IOV_MAX</option>,
 4587             and the default is 64.
 4588           </simpara>
 4589         </listitem>
 4590         <listitem>
 4591           <simpara>
 4592             <command>fstrm-set-reopen-interval</command>:
 4593             The number of seconds to wait between attempts to
 4594             reopen a closed output stream. The minimum is 1 second,
 4595             the maximum is 600 seconds (10 minutes), and the default
 4596             is 5 seconds.
 4597           </simpara>
 4598         </listitem>
 4599           </itemizedlist>
 4600           <para>
 4601         Note that all of the above minimum, maximum, and default
 4602         values are set by the <command>libfstrm</command> library,
 4603         and may be subject to change in future versions of the
 4604         library. See the <command>libfstrm</command> documentation
 4605         for more information.
 4606           </para>
 4607         </listitem>
 4608       </varlistentry>
 4609 
 4610       <varlistentry>
 4611         <term><command>dnstap-output</command></term>
 4612         <listitem>
 4613           <para>
 4614         This configures the path to which the <command>dnstap</command>
 4615         frame stream is sent if <command>dnstap</command>
 4616         is enabled at compile time and active.
 4617           </para>
 4618           <para>
 4619         The first argument is either <literal>file</literal> or
 4620         <literal>unix</literal>, indicating whether the destination
 4621         is a file or a Unix domain socket.  The second argument
 4622         is the path of the file or socket.  (Note: when using a
 4623         socket, <command>dnstap</command> messages are
 4624         only sent if another process such as
 4625         <command>fstrm_capture</command>
 4626         (provided with <command>libfstrm</command>) is listening on
 4627         the socket.)
 4628           </para>
 4629           <para>
 4630         <command>dnstap-output</command> can only be set globally
 4631         in <command>options</command>. Currently, it can only be
 4632         set once while <command>named</command> is running;
 4633         once set, it cannot be changed by
 4634         <command>rndc reload</command> or
 4635         <command>rndc reconfig</command>.
 4636           </para>
 4637         </listitem>
 4638       </varlistentry>
 4639 
 4640       <varlistentry>
 4641         <term><command>dnstap-identity</command></term>
 4642         <listitem>
 4643           <para>
 4644         This specifies an <command>identity</command> string to send in
 4645         <command>dnstap</command> messages. If set to
 4646         <literal>hostname</literal>, which is the default, the
 4647         server's hostname is sent. If set to
 4648         <literal>none</literal>, no identity string is sent.
 4649           </para>
 4650         </listitem>
 4651       </varlistentry>
 4652 
 4653       <varlistentry>
 4654         <term><command>dnstap-version</command></term>
 4655         <listitem>
 4656           <para>
 4657         This specifies a <command>version</command> string to send in
 4658         <command>dnstap</command> messages. The default is the
 4659         version number of the <acronym>BIND</acronym> release. If set to
 4660         <literal>none</literal>, no version string is sent.
 4661           </para>
 4662         </listitem>
 4663       </varlistentry>
 4664 
 4665       <varlistentry>
 4666         <term><command>geoip-directory</command></term>
 4667         <listitem>
 4668           <para>
 4669         When <command>named</command> is compiled using the
 4670         MaxMind GeoIP2 geolocation API, or the legacy GeoIP API,
 4671         this specifies the directory containing GeoIP
 4672         database files.  By default, the option is set based on
 4673         the prefix used to build the <command>libmaxminddb</command>
 4674         module; for example, if the library is installed in
 4675         <filename>/usr/local/lib</filename>, then the default
 4676         <command>geoip-directory</command> is
 4677         <filename>/usr/local/share/GeoIP</filename>. On Windows,
 4678         the default is the <command>named</command> working
 4679         directory.  See <xref linkend="acl"/> for details about
 4680         <command>geoip</command> ACLs.
 4681           </para>
 4682         </listitem>
 4683       </varlistentry>
 4684 
 4685       <varlistentry>
 4686         <term><command>key-directory</command></term>
 4687         <listitem>
 4688           <para>
 4689         This is the
 4690         directory where the public and private DNSSEC key files
 4691         should be found when performing a dynamic update of secure zones, if different than the current working
 4692         directory.  (Note that this option has no effect on the
 4693         paths for files containing non-DNSSEC keys such as
 4694         <filename>bind.keys</filename>,
 4695         <filename>rndc.key</filename>, or
 4696         <filename>session.key</filename>.)
 4697           </para>
 4698         </listitem>
 4699       </varlistentry>
 4700 
 4701       <varlistentry>
 4702         <term><command>lmdb-mapsize</command></term>
 4703         <listitem>
 4704           <para>
 4705         When <command>named</command> is built with liblmdb,
 4706         this option sets a maximum size for the memory map of
 4707         the new-zone database (NZD) in LMDB database format.
 4708         This database is used to store configuration information
 4709         for zones added using <command>rndc addzone</command>.
 4710         Note that this is not the NZD database file size, but
 4711         the largest size that the database may grow to.
 4712           </para>
 4713           <para>
 4714         Because the database file is memory mapped, its size is
 4715         limited by the address space of the <command>named</command> process.  The
 4716         default of 32 megabytes was chosen to be usable with
 4717         32-bit <command>named</command> builds.  The largest
 4718         permitted value is 1 terabyte. Given typical zone
 4719         configurations without elaborate ACLs, a 32 MB NZD file
 4720         ought to be able to hold configurations of about 100,000
 4721         zones.
 4722           </para>
 4723         </listitem>
 4724       </varlistentry>
 4725 
 4726       <varlistentry>
 4727         <term><command>managed-keys-directory</command></term>
 4728         <listitem>
 4729           <para>
 4730         This specifies the directory in which to store the files that
 4731         track managed DNSSEC keys.  By default, this is the working
 4732         directory.  The directory <emphasis>must</emphasis>
 4733         be writable by the effective user ID of the
 4734         <command>named</command> process.
 4735           </para>
 4736           <para>
 4737         If <command>named</command> is not configured to use views,
 4738         managed keys for the server are tracked in a single
 4739         file called <filename>managed-keys.bind</filename>.
 4740         Otherwise, managed keys are tracked in separate files,
 4741         one file per view; each file name is the view name
 4742         (or, if it contains characters that are incompatible with
 4743         use as a file name, the SHA256 hash of the view name),
 4744         followed by the extension
 4745         <filename>.mkeys</filename>.
 4746           </para>
 4747           <para>
 4748         (Note: in earlier releases, file names for views
 4749         always used the SHA256 hash of the view name. To ensure
 4750         compatibility after upgrading, if a file using the old
 4751         name format is found to exist, it is used instead
 4752         of the new format.)
 4753           </para>
 4754         </listitem>
 4755       </varlistentry>
 4756 
 4757       <varlistentry>
 4758         <term><command>named-xfer</command></term>
 4759         <listitem>
 4760           <para>
 4761         <emphasis>This option is obsolete.</emphasis>
 4762         In <acronym>BIND</acronym> 9, no separate
 4763         <command>named-xfer</command> program is needed;
 4764         its functionality is built into the name server.
 4765           </para>
 4766         </listitem>
 4767       </varlistentry>
 4768 
 4769       <varlistentry>
 4770         <term><command>tkey-gssapi-keytab</command></term>
 4771         <listitem>
 4772           <para>
 4773         This is the KRB5 keytab file to use for GSS-TSIG updates. If
 4774         this option is set and tkey-gssapi-credential is not
 4775         set, updates are allowed with any key
 4776         matching a principal in the specified keytab.
 4777           </para>
 4778         </listitem>
 4779       </varlistentry>
 4780 
 4781       <varlistentry>
 4782         <term><command>tkey-gssapi-credential</command></term>
 4783         <listitem>
 4784           <para>
 4785         This is the security credential with which the server should
 4786         authenticate keys requested by the GSS-TSIG protocol.
 4787         Currently only Kerberos 5 authentication is available;
 4788         the credential is a Kerberos principal which the
 4789         server can acquire through the default system key
 4790         file, normally <filename>/etc/krb5.keytab</filename>.
 4791         The location of the keytab file can be overridden using the
 4792         <command>tkey-gssapi-keytab</command> option. Normally this principal is
 4793         of the form "<userinput>DNS/</userinput><varname>server.domain</varname>".
 4794         To use GSS-TSIG, <command>tkey-domain</command> must
 4795         also be set if a specific keytab is not set with
 4796         <command>tkey-gssapi-keytab</command>.
 4797           </para>
 4798         </listitem>
 4799       </varlistentry>
 4800 
 4801       <varlistentry>
 4802         <term><command>tkey-domain</command></term>
 4803         <listitem>
 4804           <para>
 4805         This domain is appended to the names of all shared keys
 4806         generated with <command>TKEY</command>.  When a
 4807         client requests a <command>TKEY</command> exchange,
 4808         it may or may not specify the desired name for the
 4809         key. If present, the name of the shared key is
 4810         <varname>client-specified part</varname> +
 4811         <varname>tkey-domain</varname>.  Otherwise, the
 4812         name of the shared key is <varname>random hex
 4813         digits</varname> + <varname>tkey-domain</varname>.
 4814         In most cases, the <command>domainname</command>
 4815         should be the server's domain name, or an otherwise
 4816         nonexistent subdomain like
 4817         "_tkey.<varname>domainname</varname>".  If
 4818         using GSS-TSIG, this variable must be defined, unless
 4819         a specific keytab is specified using <command>tkey-gssapi-keytab</command>.
 4820           </para>
 4821         </listitem>
 4822       </varlistentry>
 4823 
 4824       <varlistentry>
 4825         <term><command>tkey-dhkey</command></term>
 4826         <listitem>
 4827           <para>
 4828         This is the Diffie-Hellman key used by the server
 4829         to generate shared keys with clients using the Diffie-Hellman
 4830         mode
 4831         of <command>TKEY</command>. The server must be
 4832         able to load the
 4833         public and private keys from files in the working directory.
 4834         In
 4835         most cases, the <varname>key_name</varname> should be the server's host name.
 4836           </para>
 4837         </listitem>
 4838       </varlistentry>
 4839 
 4840       <varlistentry>
 4841         <term><command>cache-file</command></term>
 4842         <listitem>
 4843           <para>
 4844         This is for testing only.  Do not use.
 4845           </para>
 4846         </listitem>
 4847       </varlistentry>
 4848 
 4849       <varlistentry>
 4850         <term><command>dump-file</command></term>
 4851         <listitem>
 4852           <para>
 4853         This is the pathname of the file the server dumps
 4854         the database to, when instructed to do so with
 4855         <command>rndc dumpdb</command>.
 4856         If not specified, the default is <filename>named_dump.db</filename>.
 4857           </para>
 4858         </listitem>
 4859       </varlistentry>
 4860 
 4861       <varlistentry>
 4862         <term><command>memstatistics-file</command></term>
 4863         <listitem>
 4864           <para>
 4865         This is the pathname of the file the server writes memory
 4866         usage statistics to on exit. If not specified,
 4867         the default is <filename>named.memstats</filename>.
 4868           </para>
 4869         </listitem>
 4870       </varlistentry>
 4871 
 4872       <varlistentry>
 4873         <term><command>lock-file</command></term>
 4874         <listitem>
 4875           <para>
 4876         This is the pathname of a file on which <command>named</command>
 4877         attempts to acquire a file lock when starting for
 4878         the first time; if unsuccessful, the server
 4879         terminates, under the assumption that another
 4880         server is already running.  If not specified, the default is
 4881         <filename>none</filename>.
 4882           </para>
 4883           <para>
 4884         Specifying <command>lock-file none</command> disables the
 4885         use of a lock file.  <command>lock-file</command> is
 4886         ignored if <command>named</command> was run using the <option>-X</option>
 4887         option, which overrides it.  Changes to
 4888         <command>lock-file</command> are ignored if
 4889         <command>named</command> is being reloaded or
 4890         reconfigured; it is only effective when the server is
 4891         first started.
 4892           </para>
 4893         </listitem>
 4894       </varlistentry>
 4895 
 4896       <varlistentry>
 4897         <term><command>pid-file</command></term>
 4898         <listitem>
 4899           <para>
 4900         This is the pathname of the file the server writes its process ID
 4901         in. If not specified, the default is
 4902         <filename>/var/run/named/named.pid</filename>.
 4903         The PID file is used by programs that send signals to
 4904         the running
 4905         name server. Specifying <command>pid-file none</command> disables the
 4906         use of a PID file; no file is written and any
 4907         existing one is removed.  Note that <command>none</command>
 4908         is a keyword, not a filename, and therefore is not enclosed
 4909         in
 4910         double quotes.
 4911           </para>
 4912         </listitem>
 4913       </varlistentry>
 4914 
 4915       <varlistentry>
 4916         <term><command>recursing-file</command></term>
 4917         <listitem>
 4918           <para>
 4919         This is the pathname of the file where the server dumps
 4920         the queries that are currently recursing, when instructed
 4921         to do so with <command>rndc recursing</command>.
 4922         If not specified, the default is <filename>named.recursing</filename>.
 4923           </para>
 4924         </listitem>
 4925       </varlistentry>
 4926 
 4927       <varlistentry>
 4928         <term><command>statistics-file</command></term>
 4929         <listitem>
 4930           <para>
 4931         This is the pathname of the file the server appends statistics
 4932         to, when instructed to do so using <command>rndc stats</command>.
 4933         If not specified, the default is <filename>named.stats</filename> in the
 4934         server's current directory.  The format of the file is
 4935         described
 4936         in <xref linkend="statsfile"/>.
 4937           </para>
 4938         </listitem>
 4939       </varlistentry>
 4940 
 4941       <varlistentry>
 4942         <term><command>bindkeys-file</command></term>
 4943         <listitem>
 4944           <para>
 4945         This is the pathname of a file to override the built-in trusted
 4946         keys provided by <command>named</command>.
 4947         See the discussion of <command>dnssec-validation</command>
 4948         for details.  If not specified, the default is
 4949         <filename>/etc/bind.keys</filename>.
 4950           </para>
 4951         </listitem>
 4952       </varlistentry>
 4953 
 4954       <varlistentry>
 4955         <term><command>secroots-file</command></term>
 4956         <listitem>
 4957           <para>
 4958         This is the pathname of the file the server dumps
 4959         security roots to, when instructed to do so with
 4960         <command>rndc secroots</command>.
 4961         If not specified, the default is
 4962         <filename>named.secroots</filename>.
 4963           </para>
 4964         </listitem>
 4965       </varlistentry>
 4966 
 4967       <varlistentry>
 4968         <term><command>session-keyfile</command></term>
 4969         <listitem>
 4970           <para>
 4971         This is the pathname of the file into which to write a TSIG
 4972         session key generated by <command>named</command> for use by
 4973         <command>nsupdate -l</command>.  If not specified, the
 4974         default is <filename>/var/run/named/session.key</filename>.
 4975         (See <xref linkend="dynamic_update_policies"/>, and in
 4976         particular the discussion of the
 4977         <command>update-policy</command> statement's
 4978         <userinput>local</userinput> option for more
 4979         information about this feature.)
 4980           </para>
 4981         </listitem>
 4982       </varlistentry>
 4983 
 4984       <varlistentry>
 4985         <term><command>session-keyname</command></term>
 4986         <listitem>
 4987           <para>
 4988         This is the key name to use for the TSIG session key.
 4989         If not specified, the default is <varname>local-ddns</varname>.
 4990           </para>
 4991         </listitem>
 4992       </varlistentry>
 4993 
 4994       <varlistentry>
 4995         <term><command>session-keyalg</command></term>
 4996         <listitem>
 4997           <para>
 4998         This is the algorithm to use for the TSIG session key.
 4999         Valid values are hmac-sha1, hmac-sha224, hmac-sha256,
 5000         hmac-sha384, hmac-sha512, and hmac-md5.  If not
 5001         specified, the default is hmac-sha256.
 5002           </para>
 5003         </listitem>
 5004       </varlistentry>
 5005 
 5006       <varlistentry>
 5007         <term><command>port</command></term>
 5008         <listitem>
 5009           <para>
 5010         This is the UDP/TCP port number the server uses to
 5011         receive and send DNS protocol traffic.
 5012         The default is 53.  This option is mainly intended for server
 5013         testing;
 5014         a server using a port other than 53 is not able to
 5015         communicate with
 5016         the global DNS.
 5017           </para>
 5018         </listitem>
 5019       </varlistentry>
 5020 
 5021       <varlistentry>
 5022         <term><command>dscp</command></term>
 5023         <listitem>
 5024           <para>
 5025         This is the global Differentiated Services Code Point (DSCP)
 5026         value to classify outgoing DNS traffic, on operating
 5027         systems that support DSCP. Valid values are 0 through 63.
 5028         It is not configured by default.
 5029           </para>
 5030         </listitem>
 5031       </varlistentry>
 5032 
 5033       <varlistentry>
 5034         <term><command>random-device</command></term>
 5035         <listitem>
 5036           <para>
 5037         This specifies a source of entropy to be used by the server.  Entropy is
 5038         primarily needed
 5039         for DNSSEC operations, such as TKEY transactions and dynamic
 5040         update of signed
 5041         zones.  This option specifies the device (or file) from which
 5042         to read
 5043         entropy.  If it is a file, operations requiring entropy will
 5044         fail when the
 5045         file has been exhausted.  If <command>random-device</command> is not specified, the default value
 5046         is
 5047         <filename>/dev/random</filename>
 5048         (or equivalent) when present, and none otherwise.  The
 5049         <command>random-device</command> option takes
 5050         effect during
 5051         the initial configuration load at server startup time and
 5052         is ignored on subsequent reloads.
 5053           </para>
 5054         </listitem>
 5055       </varlistentry>
 5056 
 5057       <varlistentry>
 5058         <term><command>preferred-glue</command></term>
 5059         <listitem>
 5060           <para>
 5061         If specified, the listed type (A or AAAA) is emitted
 5062         before other glue
 5063         in the additional section of a query response.
 5064         The default is to prefer A records when responding
 5065         to queries that arrived via IPv4 and AAAA when
 5066         responding to queries that arrived via IPv6.
 5067           </para>
 5068         </listitem>
 5069       </varlistentry>
 5070 
 5071       <varlistentry xml:id="root_delegation_only">
 5072         <term><command>root-delegation-only</command></term>
 5073         <listitem>
 5074           <para>
 5075         This turns on enforcement of delegation-only in TLDs
 5076         (top-level domains) and root zones with an optional
 5077         exclude list.
 5078           </para>
 5079           <para>
 5080         DS queries are expected to be made to and be answered by
 5081         delegation-only zones.  Such queries and responses are
 5082         treated as an exception to delegation-only processing
 5083         and are not converted to NXDOMAIN responses, provided
 5084         a CNAME is not discovered at the query name.
 5085           </para>
 5086           <para>
 5087         If a delegation-only zone server also serves a child
 5088         zone, it is not always possible to determine whether
 5089         an answer comes from the delegation-only zone or the
 5090         child zone.  SOA NS and DNSKEY records are apex-only
 5091         records and a matching response that contains
 5092         these records or DS is treated as coming from a
 5093         child zone.  RRSIG records are also examined to see
 5094         if they are signed by a child zone, and the
 5095         authority section is examined to see if there
 5096         is evidence that the answer is from the child zone.
 5097         Answers that are determined to be from a child zone
 5098         are not converted to NXDOMAIN responses.  Despite
 5099         all these checks, there is still a possibility of
 5100         false negatives when a child zone is being served.
 5101           </para>
 5102           <para>
 5103         Similarly, false positives can arise from empty nodes
 5104         (no records at the name) in the delegation-only zone
 5105         when the query type is not <varname>ANY</varname>.
 5106           </para>
 5107           <para>
 5108         Note that some TLDs are not delegation-only; e.g., "DE", "LV",
 5109         "US", and "MUSEUM".  This list is not exhaustive.
 5110           </para>
 5111 
 5112 <programlisting>
 5113 options {
 5114     root-delegation-only exclude { "de"; "lv"; "us"; "museum"; };
 5115 };
 5116 </programlisting>
 5117 
 5118         </listitem>
 5119       </varlistentry>
 5120 
 5121       <varlistentry>
 5122         <term><command>disable-algorithms</command></term>
 5123         <listitem>
 5124           <para>
 5125         This disables the specified DNSSEC algorithms at and below the
 5126         specified name.
 5127         Multiple <command>disable-algorithms</command>
 5128         statements are allowed.
 5129         Only the best-match <command>disable-algorithms</command>
 5130         clause is used to determine the algorithms.
 5131           </para>
 5132           <para>
 5133         If all supported algorithms are disabled, the zones covered
 5134         by the <command>disable-algorithms</command> setting are treated
 5135         as insecure.
 5136           </para>
 5137           <para>
 5138         Configured trust anchors in <command>trusted-keys</command>
 5139         or <command>managed-keys</command> that match a disabled
 5140         algorithm are ignored and treated as if they were not
 5141         configured.
 5142           </para>
 5143         </listitem>
 5144       </varlistentry>
 5145 
 5146       <varlistentry>
 5147         <term><command>disable-ds-digests</command></term>
 5148         <listitem>
 5149           <para>
 5150         This disables the specified DS digest types at and below the
 5151         specified name.
 5152         Multiple <command>disable-ds-digests</command>
 5153         statements are allowed.
 5154         Only the best-match <command>disable-ds-digests</command>
 5155         clause is used to determine the digest types.
 5156           </para>
 5157           <para>
 5158         If all supported digest types are disabled, the zones covered
 5159         by <command>disable-ds-digests</command> are treated
 5160         as insecure.
 5161           </para>
 5162         </listitem>
 5163       </varlistentry>
 5164 
 5165       <varlistentry>
 5166         <term><command>dnssec-lookaside</command></term>
 5167         <listitem>
 5168           <para>
 5169         When set, <command>dnssec-lookaside</command> provides the
 5170         validator with an alternate method to validate DNSKEY
 5171         records at the top of a zone.  When a DNSKEY is at or
 5172         below a domain specified by the deepest
 5173         <command>dnssec-lookaside</command>, and the normal DNSSEC
 5174         validation has left the key untrusted, the trust-anchor
 5175         is appended to the key name and a DLV record is
 5176         looked up to see if it can validate the key.  If the DLV
 5177         record validates a DNSKEY (similarly to the way a DS
 5178         record does), the DNSKEY RRset is deemed to be trusted.
 5179           </para>
 5180           <para>
 5181         If <command>dnssec-lookaside</command> is set to
 5182         <userinput>no</userinput>, then <command>dnssec-lookaside</command>
 5183         is not used.
 5184           </para>
 5185           <para>
 5186         Note: the ISC-provided DLV service at
 5187         <literal>dlv.isc.org</literal> has been shut down.
 5188         The <command>dnssec-lookaside auto;</command>
 5189         configuration option, which set <command>named</command>
 5190         to use ISC DLV with minimal configuration, has
 5191         accordingly been removed.
 5192           </para>
 5193         </listitem>
 5194       </varlistentry>
 5195 
 5196       <varlistentry>
 5197         <term><command>dnssec-must-be-secure</command></term>
 5198         <listitem>
 5199           <para>
 5200         This specifies hierarchies which must be or may not be secure
 5201         (signed and validated).  If <userinput>yes</userinput>,
 5202         then <command>named</command> only accepts answers if
 5203         they are secure.  If <userinput>no</userinput>, then normal
 5204         DNSSEC validation applies, allowing insecure answers to
 5205         be accepted.  The specified domain must be under a
 5206         <command>trusted-keys</command> or
 5207         <command>managed-keys</command> statement, or
 5208         <command>dnssec-validation auto</command> must be active.
 5209           </para>
 5210         </listitem>
 5211       </varlistentry>
 5212 
 5213       <varlistentry>
 5214         <term><command>dns64</command></term>
 5215         <listitem>
 5216           <para>
 5217         This directive instructs <command>named</command> to
 5218         return mapped IPv4 addresses to AAAA queries when
 5219         there are no AAAA records.  It is intended to be
 5220         used in conjunction with a NAT64.  Each
 5221         <command>dns64</command> defines one DNS64 prefix.
 5222         Multiple DNS64 prefixes can be defined.
 5223           </para>
 5224           <para>
 5225         Compatible IPv6 prefixes have lengths of 32, 40, 48, 56,
 5226         64, and 96, per RFC 6052.  Bits 64..71 inclusive must
 5227         be zero, with the most significant bit of the prefix in
 5228         position 0.
 5229           </para>
 5230           <para>
 5231         In addition, a reverse IP6.ARPA zone is created for
 5232         the prefix to provide a mapping from the IP6.ARPA names
 5233         to the corresponding IN-ADDR.ARPA names using synthesized
 5234         CNAMEs.  <command>dns64-server</command> and
 5235         <command>dns64-contact</command> can be used to specify
 5236         the name of the server and contact for the zones. These
 5237         can be set at the view/options level but not
 5238         on a per-prefix basis.
 5239           </para>
 5240           <para>
 5241         Each <command>dns64</command> supports an optional
 5242         <command>clients</command> ACL that determines which
 5243         clients are affected by this directive.  If not defined,
 5244         it defaults to <userinput>any;</userinput>.
 5245           </para>
 5246           <para>
 5247         Each <command>dns64</command> supports an optional
 5248         <command>mapped</command> ACL that selects which
 5249         IPv4 addresses are to be mapped in the corresponding
 5250         A RRset.  If not defined, it defaults to
 5251         <userinput>any;</userinput>.
 5252           </para>
 5253           <para>
 5254         Normally, DNS64 does not apply to a domain name that
 5255         owns one or more AAAA records; these records are
 5256         simply returned.  The optional
 5257         <command>exclude</command> ACL allows specification
 5258         of a list of IPv6 addresses that are ignored
 5259         if they appear in a domain name's AAAA records;
 5260         DNS64 is applied to any A records the domain
 5261         name owns.  If not defined, <command>exclude</command>
 5262         defaults to ::ffff:0.0.0.0/96.
 5263           </para>
 5264           <para>
 5265         A optional <command>suffix</command> can also
 5266         be defined to set the bits trailing the mapped
 5267         IPv4 address bits.  By default these bits are
 5268         set to <userinput>::</userinput>.  The bits
 5269         matching the prefix and mapped IPv4 address
 5270         must be zero.
 5271           </para>
 5272           <para>
 5273         If <command>recursive-only</command> is set to
 5274         <command>yes</command>, the DNS64 synthesis
 5275         only happens for recursive queries.  The default
 5276         is <command>no</command>.
 5277           </para>
 5278           <para>
 5279         If <command>break-dnssec</command> is set to
 5280         <command>yes</command>, the DNS64 synthesis
 5281         happens even if the result, if validated, would
 5282         cause a DNSSEC validation failure.  If this option
 5283         is set to <command>no</command> (the default), the DO
 5284         is set on the incoming query, and there are RRSIGs on
 5285         the applicable records, then synthesis does not happen.
 5286           </para>
 5287 <programlisting>
 5288     acl rfc1918 { 10/8; 192.168/16; 172.16/12; };
 5289 
 5290     dns64 64:FF9B::/96 {
 5291         clients { any; };
 5292         mapped { !rfc1918; any; };
 5293         exclude { 64:FF9B::/96; ::ffff:0000:0000/96; };
 5294         suffix ::;
 5295     };
 5296 </programlisting>
 5297         </listitem>
 5298       </varlistentry>
 5299 
 5300       <varlistentry>
 5301         <term><command>dnssec-loadkeys-interval</command></term>
 5302         <listitem>
 5303         <para>
 5304           When a zone is configured with <command>auto-dnssec
 5305           maintain;</command>, its key repository must be checked
 5306           periodically to see if any new keys have been added
 5307           or any existing keys' timing metadata has been updated
 5308           (see <xref linkend="man.dnssec-keygen"/> and
 5309           <xref linkend="man.dnssec-settime"/>).  The
 5310           <command>dnssec-loadkeys-interval</command> option
 5311           sets the frequency of automatic repository checks, in
 5312           minutes.  The default is <literal>60</literal> (1 hour),
 5313           the minimum is <literal>1</literal> (1 minute), and the
 5314           maximum is <literal>1440</literal> (24 hours); any higher
 5315           value is silently reduced.
 5316         </para>
 5317         </listitem>
 5318       </varlistentry>
 5319 
 5320       <varlistentry>
 5321         <term><command>dnssec-update-mode</command></term>
 5322         <listitem>
 5323         <para>
 5324           If this option is set to its default value of
 5325           <literal>maintain</literal> in a zone of type
 5326           <literal>master</literal> which is DNSSEC-signed
 5327           and configured to allow dynamic updates (see
 5328           <xref linkend="dynamic_update_policies"/>), and
 5329           if <command>named</command> has access to the
 5330           private signing key(s) for the zone, then
 5331           <command>named</command> automatically signs all new
 5332           or changed records and maintains signatures for the zone
 5333           by regenerating RRSIG records whenever they approach
 5334           their expiration date.
 5335         </para>
 5336         <para>
 5337           If the option is changed to <literal>no-resign</literal>,
 5338           then <command>named</command> signs all new or
 5339           changed records, but scheduled maintenance of
 5340           signatures is disabled.
 5341         </para>
 5342         <para>
 5343           With either of these settings, <command>named</command>
 5344           rejects updates to a DNSSEC-signed zone when the
 5345           signing keys are inactive or unavailable to
 5346           <command>named</command>.  (A planned third option,
 5347           <literal>external</literal>, will disable all automatic
 5348           signing and allow DNSSEC data to be submitted into a zone
 5349           via dynamic update; this is not yet implemented.)
 5350         </para>
 5351         </listitem>
 5352       </varlistentry>
 5353 
 5354       <varlistentry>
 5355         <term><command>nta-lifetime</command></term>
 5356         <listitem>
 5357         <para>
 5358           This specifies the default lifetime, in seconds,
 5359           for negative trust anchors added
 5360           via <command>rndc nta</command>.
 5361         </para>
 5362         <para>
 5363           A negative trust anchor selectively disables
 5364           DNSSEC validation for zones that are known to be
 5365           failing because of misconfiguration, rather than
 5366           an attack.  When data to be validated is
 5367           at or below an active NTA (and above any other
 5368           configured trust anchors), <command>named</command>
 5369           aborts the DNSSEC validation process and treats the data as
 5370           insecure rather than bogus.  This continues until the
 5371           NTA's lifetime is elapsed. NTAs persist
 5372           across <command>named</command> restarts.
 5373         </para>
 5374         <para>
 5375           For convenience, TTL-style time-unit suffixes can be
 5376           used to specify the NTA lifetime in seconds, minutes,
 5377           or hours.  <option>nta-lifetime</option> defaults to
 5378           one hour; it cannot exceed one week.
 5379         </para>
 5380         </listitem>
 5381       </varlistentry>
 5382 
 5383       <varlistentry>
 5384         <term><command>nta-recheck</command></term>
 5385         <listitem>
 5386         <para>
 5387           This specifies how often to check whether negative
 5388           trust anchors added via <command>rndc nta</command>
 5389           are still necessary.
 5390         </para>
 5391         <para>
 5392           A negative trust anchor is normally used when a
 5393           domain has stopped validating due to operator error;
 5394           it temporarily disables DNSSEC validation for that
 5395           domain. In the interest of ensuring that DNSSEC
 5396           validation is turned back on as soon as possible,
 5397           <command>named</command> periodically sends a
 5398           query to the domain, ignoring negative trust anchors,
 5399           to find out whether it can now be validated.  If so,
 5400           the negative trust anchor is allowed to expire early.
 5401         </para>
 5402         <para>
 5403           Validity checks can be disabled for an individual
 5404           NTA by using <command>rndc nta -f</command>, or
 5405           for all NTAs by setting <option>nta-recheck</option>
 5406           to zero.
 5407         </para>
 5408         <para>
 5409           For convenience, TTL-style time-unit suffixes can be
 5410           used to specify the NTA recheck interval in seconds,
 5411           minutes, or hours.  The default is five minutes.  It
 5412           cannot be longer than <option>nta-lifetime</option>,
 5413           which cannot be longer than a week.
 5414         </para>
 5415         </listitem>
 5416       </varlistentry>
 5417 
 5418 
 5419       <varlistentry>
 5420         <term><command>max-zone-ttl</command></term>
 5421         <listitem>
 5422           <para>
 5423         This specifies a maximum permissible TTL value in seconds.
 5424         For convenience, TTL-style time-unit suffixes may be
 5425         used to specify the maximum value.
 5426         When loading a zone file using a
 5427         <option>masterfile-format</option> of
 5428         <constant>text</constant> or <constant>raw</constant>,
 5429         any record encountered with a TTL higher than
 5430         <option>max-zone-ttl</option> causes the zone to
 5431         be rejected.
 5432           </para>
 5433           <para>
 5434         This is useful in DNSSEC-signed zones because when
 5435         rolling to a new DNSKEY, the old key needs to remain
 5436         available until RRSIG records have expired from
 5437         caches.  The <option>max-zone-ttl</option> option guarantees
 5438         that the largest TTL in the zone is no higher
 5439         than the set value.
 5440           </para>
 5441           <para>
 5442         (Note: because <constant>map</constant>-format files
 5443         load directly into memory, this option cannot be
 5444         used with them.)
 5445           </para>
 5446           <para>
 5447         The default value is <constant>unlimited</constant>.
 5448         A <option>max-zone-ttl</option> of zero is treated as
 5449         <constant>unlimited</constant>.
 5450           </para>
 5451         </listitem>
 5452       </varlistentry>
 5453 
 5454       <varlistentry>
 5455         <term><command>serial-update-method</command></term>
 5456         <listitem>
 5457           <para>
 5458         Zones configured for dynamic DNS may use this
 5459         option to set the update method to be used for
 5460         the zone serial number in the SOA record.
 5461           </para>
 5462           <para>
 5463         With the default setting of
 5464         <command>serial-update-method increment;</command>, the
 5465         SOA serial number is incremented by one each time
 5466         the zone is updated.
 5467           </para>
 5468           <para>
 5469         When set to
 5470         <command>serial-update-method unixtime;</command>, the
 5471         SOA serial number is set to the number of seconds
 5472         since the Unix epoch, unless the serial number is
 5473         already greater than or equal to that value, in which
 5474         case it is simply incremented by one.
 5475           </para>
 5476           <para>
 5477         When set to
 5478         <command>serial-update-method date;</command>, the
 5479         new SOA serial number is the current date
 5480         in the form "YYYYMMDD", followed by two zeroes,
 5481         unless the existing serial number is already greater
 5482         than or equal to that value, in which case it is
 5483         incremented by one.
 5484           </para>
 5485         </listitem>
 5486       </varlistentry>
 5487 
 5488       <varlistentry>
 5489         <term><command>zone-statistics</command></term>
 5490         <listitem>
 5491           <para>
 5492         If <userinput>full</userinput>, the server collects
 5493         statistical data on all zones, unless specifically
 5494         turned off on a per-zone basis by specifying
 5495         <command>zone-statistics terse</command> or
 5496         <command>zone-statistics none</command>
 5497         in the <command>zone</command> statement.
 5498         The default is <userinput>terse</userinput>, providing
 5499         minimal statistics on zones (including name and
 5500         current serial number, but not query type
 5501         counters).
 5502           </para>
 5503           <para>
 5504         These statistics may be accessed via the
 5505         <command>statistics-channel</command> or
 5506         using <command>rndc stats</command>, which
 5507         dumps them to the file listed
 5508         in the <command>statistics-file</command>.  See
 5509         also <xref linkend="statsfile"/>.
 5510           </para>
 5511           <para>
 5512         For backward compatibility with earlier versions
 5513         of BIND 9, the <command>zone-statistics</command>
 5514         option can also accept <userinput>yes</userinput>
 5515         or <userinput>no</userinput>; <userinput>yes</userinput>
 5516         has the same meaning as <userinput>full</userinput>.
 5517         As of <acronym>BIND</acronym> 9.10,
 5518         <userinput>no</userinput> has the same meaning
 5519         as <userinput>none</userinput>; previously, it
 5520         was the same as <userinput>terse</userinput>.
 5521           </para>
 5522         </listitem>
 5523       </varlistentry>
 5524     </variablelist>
 5525 
 5526     <section xml:id="boolean_options"><info><title>Boolean Options</title></info>
 5527 
 5528       <variablelist>
 5529 
 5530         <varlistentry>
 5531           <term><command>automatic-interface-scan</command></term>
 5532           <listitem>
 5533         <para>
 5534           If <userinput>yes</userinput> and supported by the operating
 5535           system, this automatically rescans network interfaces when the
 5536           interface addresses are added or removed.  The default is
 5537           <userinput>yes</userinput>.  This configuration option does
 5538           not affect the time-based <command>interface-interval</command>
 5539           option; it is recommended to set the time-based
 5540           <command>interface-interval</command> to 0 when the operator
 5541           confirms that automatic interface scanning is supported by the
 5542           operating system.
 5543         </para>
 5544         <para>
 5545           The <command>automatic-interface-scan</command> implementation
 5546           uses routing sockets for the network interface discovery;
 5547           therefore, the operating system must support the routing
 5548           sockets for this feature to work.
 5549         </para>
 5550           </listitem>
 5551         </varlistentry>
 5552 
 5553         <varlistentry>
 5554           <term><command>allow-new-zones</command></term>
 5555           <listitem>
 5556         <para>
 5557           If <userinput>yes</userinput>, then zones can be
 5558           added at runtime via <command>rndc addzone</command>.
 5559           The default is <userinput>no</userinput>.
 5560         </para>
 5561         <para>
 5562           Newly added zones' configuration parameters
 5563           are stored so that they can persist after the
 5564           server is restarted.  The configuration information
 5565           is saved in a file called
 5566           <filename><replaceable>viewname</replaceable>.nzf</filename>
 5567           (or, if <command>named</command> is compiled with
 5568           liblmdb, in an LMDB database file called
 5569           <filename><replaceable>viewname</replaceable>.nzd</filename>).
 5570           <replaceable>viewname</replaceable> is the name of the
 5571           view, unless the view name contains characters that are
 5572           incompatible with use as a file name, in which case a
 5573           cryptographic hash of the view name is used instead.
 5574         </para>
 5575         <para>
 5576           Configurations for zones added at runtime are
 5577           stored either in a new-zone file (NZF) or a new-zone
 5578           database (NZD), depending on whether
 5579           <command>named</command> was linked with
 5580           liblmdb at compile time.
 5581           See <xref linkend="man.rndc"/> for further details
 5582           about <command>rndc addzone</command>.
 5583         </para>
 5584           </listitem>
 5585         </varlistentry>
 5586 
 5587         <varlistentry>
 5588           <term><command>auth-nxdomain</command></term>
 5589           <listitem>
 5590         <para>
 5591           If <userinput>yes</userinput>, then the <command>AA</command> bit
 5592           is always set on NXDOMAIN responses, even if the server is
 5593           not actually
 5594           authoritative. The default is <userinput>no</userinput>.
 5595         </para>
 5596           </listitem>
 5597         </varlistentry>
 5598 
 5599         <varlistentry>
 5600           <term><command>deallocate-on-exit</command></term>
 5601           <listitem>
 5602         <para>
 5603           This option was used in <acronym>BIND</acronym>
 5604           8 to enable checking
 5605           for memory leaks on exit. <acronym>BIND</acronym> 9 ignores the option and always performs
 5606           the checks.
 5607         </para>
 5608           </listitem>
 5609         </varlistentry>
 5610 
 5611         <varlistentry>
 5612           <term><command>memstatistics</command></term>
 5613           <listitem>
 5614         <para>
 5615           This writes memory statistics to the file specified by
 5616           <command>memstatistics-file</command> at exit.
 5617           The default is <userinput>no</userinput> unless
 5618           <userinput>-m record</userinput> is specified on the command line, in
 5619           which case it is <userinput>yes</userinput>.
 5620         </para>
 5621           </listitem>
 5622         </varlistentry>
 5623 
 5624         <varlistentry>
 5625           <term><command>dialup</command></term>
 5626           <listitem>
 5627         <para>
 5628           If <userinput>yes</userinput>, then the
 5629           server treats all zones as if they are doing zone transfers
 5630           across
 5631           a dial-on-demand dialup link, which can be brought up by
 5632           traffic
 5633           originating from this server. Although this setting has different effects
 5634           according
 5635           to zone type, it concentrates the zone maintenance so that
 5636           everything
 5637           happens quickly, once every <command>heartbeat-interval</command>,
 5638           ideally during a single call. It also suppresses some
 5639           normal
 5640           zone maintenance traffic. The default is <userinput>no</userinput>.
 5641         </para>
 5642         <para>
 5643           If specified in the <command>view</command> and
 5644           <command>zone</command> statements, the <command>dialup</command> option
 5645           overrides the global <command>dialup</command> option.
 5646         </para>
 5647         <para>
 5648           If the zone is a primary zone, the server sends out a
 5649           NOTIFY
 5650           request to all the secondaries (default). This should trigger the
 5651           zone serial
 5652           number check in the secondary (providing it supports NOTIFY),
 5653           allowing the secondary
 5654           to verify the zone while the connection is active.
 5655           The set of servers to which NOTIFY is sent can be controlled
 5656           by
 5657           <command>notify</command> and <command>also-notify</command>.
 5658         </para>
 5659         <para>
 5660           If the
 5661           zone is a secondary or stub zone, the server suppresses
 5662           the regular
 5663           "zone up to date" (refresh) queries and only performs them
 5664           when the
 5665           <command>heartbeat-interval</command> expires, in
 5666           addition to sending
 5667           NOTIFY requests.
 5668         </para>
 5669         <para>
 5670           Finer control can be achieved by using
 5671           <userinput>notify</userinput>, which only sends NOTIFY
 5672           messages;
 5673           <userinput>notify-passive</userinput>, which sends NOTIFY
 5674           messages and
 5675           suppresses the normal refresh queries; <userinput>refresh</userinput>,
 5676           which suppresses normal refresh processing and sends refresh
 5677           queries
 5678           when the <command>heartbeat-interval</command>
 5679           expires; and
 5680           <userinput>passive</userinput>, which disables normal
 5681           refresh
 5682           processing.
 5683         </para>
 5684 
 5685         <informaltable colsep="0" rowsep="0">
 5686           <tgroup cols="4" colsep="0" rowsep="0" tgroupstyle="4Level-table">
 5687             <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/>
 5688             <colspec colname="2" colnum="2" colsep="0" colwidth="1.150in"/>
 5689             <colspec colname="3" colnum="3" colsep="0" colwidth="1.150in"/>
 5690             <colspec colname="4" colnum="4" colsep="0" colwidth="1.150in"/>
 5691             <tbody>
 5692               <row rowsep="0">
 5693             <entry colname="1">
 5694               <para>
 5695                 dialup mode
 5696               </para>
 5697             </entry>
 5698             <entry colname="2">
 5699               <para>
 5700                 normal refresh
 5701               </para>
 5702             </entry>
 5703             <entry colname="3">
 5704               <para>
 5705                 heart-beat refresh
 5706               </para>
 5707             </entry>
 5708             <entry colname="4">
 5709               <para>
 5710                 heart-beat notify
 5711               </para>
 5712             </entry>
 5713               </row>
 5714               <row rowsep="0">
 5715             <entry colname="1">
 5716               <para><command>no</command> (default)</para>
 5717             </entry>
 5718             <entry colname="2">
 5719               <para>
 5720                 yes
 5721               </para>
 5722             </entry>
 5723             <entry colname="3">
 5724               <para>
 5725                 no
 5726               </para>
 5727             </entry>
 5728             <entry colname="4">
 5729               <para>
 5730                 no
 5731               </para>
 5732             </entry>
 5733               </row>
 5734               <row rowsep="0">
 5735             <entry colname="1">
 5736               <para><command>yes</command></para>
 5737             </entry>
 5738             <entry colname="2">
 5739               <para>
 5740                 no
 5741               </para>
 5742             </entry>
 5743             <entry colname="3">
 5744               <para>
 5745                 yes
 5746               </para>
 5747             </entry>
 5748             <entry colname="4">
 5749               <para>
 5750                 yes
 5751               </para>
 5752             </entry>
 5753               </row>
 5754               <row rowsep="0">
 5755             <entry colname="1">
 5756               <para><command>notify</command></para>
 5757             </entry>
 5758             <entry colname="2">
 5759               <para>
 5760                 yes
 5761               </para>
 5762             </entry>
 5763             <entry colname="3">
 5764               <para>
 5765                 no
 5766               </para>
 5767             </entry>
 5768             <entry colname="4">
 5769               <para>
 5770                 yes
 5771               </para>
 5772             </entry>
 5773               </row>
 5774               <row rowsep="0">
 5775             <entry colname="1">
 5776               <para><command>refresh</command></para>
 5777             </entry>
 5778             <entry colname="2">
 5779               <para>
 5780                 no
 5781               </para>
 5782             </entry>
 5783             <entry colname="3">
 5784               <para>
 5785                 yes
 5786               </para>
 5787             </entry>
 5788             <entry colname="4">
 5789               <para>
 5790                 no
 5791               </para>
 5792             </entry>
 5793               </row>
 5794               <row rowsep="0">
 5795             <entry colname="1">
 5796               <para><command>passive</command></para>
 5797             </entry>
 5798             <entry colname="2">
 5799               <para>
 5800                 no
 5801               </para>
 5802             </entry>
 5803             <entry colname="3">
 5804               <para>
 5805                 no
 5806               </para>
 5807             </entry>
 5808             <entry colname="4">
 5809               <para>
 5810                 no
 5811               </para>
 5812             </entry>
 5813               </row>
 5814               <row rowsep="0">
 5815             <entry colname="1">
 5816               <para><command>notify-passive</command></para>
 5817             </entry>
 5818             <entry colname="2">
 5819               <para>
 5820                 no
 5821               </para>
 5822             </entry>
 5823             <entry colname="3">
 5824               <para>
 5825                 no
 5826               </para>
 5827             </entry>
 5828             <entry colname="4">
 5829               <para>
 5830                 yes
 5831               </para>
 5832             </entry>
 5833               </row>
 5834             </tbody>
 5835           </tgroup>
 5836         </informaltable>
 5837 
 5838         <para>
 5839           Note that normal NOTIFY processing is not affected by
 5840           <command>dialup</command>.
 5841         </para>
 5842 
 5843           </listitem>
 5844         </varlistentry>
 5845 
 5846         <varlistentry>
 5847           <term><command>fake-iquery</command></term>
 5848           <listitem>
 5849         <para>
 5850           In <acronym>BIND</acronym> 8, this option
 5851           enabled simulating the obsolete DNS query type
 5852           IQUERY. <acronym>BIND</acronym> 9 never does
 5853           IQUERY simulation.
 5854         </para>
 5855           </listitem>
 5856         </varlistentry>
 5857 
 5858         <varlistentry>
 5859           <term><command>fetch-glue</command></term>
 5860           <listitem>
 5861         <para>
 5862           This option is obsolete.
 5863           In BIND 8, <userinput>fetch-glue yes</userinput>
 5864           caused the server to attempt to fetch glue resource records
 5865           it
 5866           did not have when constructing the additional
 5867           data section of a response.  This is now considered a bad
 5868           idea
 5869           and BIND 9 never does it.
 5870         </para>
 5871           </listitem>
 5872         </varlistentry>
 5873 
 5874         <varlistentry>
 5875           <term><command>flush-zones-on-shutdown</command></term>
 5876           <listitem>
 5877         <para>
 5878           When the nameserver exits upon receiving SIGTERM,
 5879           flush or do not flush any pending zone writes.  The default
 5880           is
 5881           <command>flush-zones-on-shutdown</command> <userinput>no</userinput>.
 5882         </para>
 5883           </listitem>
 5884         </varlistentry>
 5885 
 5886         <varlistentry>
 5887           <term><command>geoip-use-ecs</command></term>
 5888           <listitem>
 5889         <para>
 5890           When BIND is compiled with GeoIP support and configured
 5891           with "geoip" ACL elements, this option indicates whether
 5892           the EDNS Client Subnet option, if present in a request,
 5893           should be used for matching against the GeoIP database.
 5894           The default is
 5895           <command>geoip-use-ecs</command> <userinput>yes</userinput>.
 5896         </para>
 5897           </listitem>
 5898         </varlistentry>
 5899 
 5900         <varlistentry>
 5901           <term><command>has-old-clients</command></term>
 5902           <listitem>
 5903         <para>
 5904           This option was incorrectly implemented
 5905           in <acronym>BIND</acronym> 8, and is ignored by <acronym>BIND</acronym> 9.
 5906           To achieve the intended effect
 5907           of
 5908           <command>has-old-clients</command> <userinput>yes</userinput>, specify
 5909           the two separate options <command>auth-nxdomain</command> <userinput>yes</userinput>
 5910           and <command>rfc2308-type1</command> <userinput>no</userinput> instead.
 5911         </para>
 5912           </listitem>
 5913         </varlistentry>
 5914 
 5915         <varlistentry>
 5916           <term><command>host-statistics</command></term>
 5917           <listitem>
 5918         <para>
 5919           In BIND 8, this enabled keeping of
 5920           statistics for every host that the name server interacts
 5921           with.
 5922           It is not implemented in BIND 9.
 5923         </para>
 5924           </listitem>
 5925         </varlistentry>
 5926 
 5927         <varlistentry>
 5928           <term><command>root-key-sentinel</command></term>
 5929           <listitem>
 5930         <para>
 5931           If <userinput>yes</userinput>, respond to root key sentinel probes as described in
 5932           draft-ietf-dnsop-kskroll-sentinel-08. The default is
 5933           <userinput>yes</userinput>.
 5934         </para>
 5935           </listitem>
 5936         </varlistentry>
 5937 
 5938         <varlistentry>
 5939           <term><command>maintain-ixfr-base</command></term>
 5940           <listitem>
 5941         <para>
 5942           <emphasis>This option is obsolete</emphasis>.
 5943           It was used in <acronym>BIND</acronym> 8 to
 5944           determine whether a transaction log was
 5945           kept for Incremental Zone Transfer. <acronym>BIND</acronym> 9 maintains a transaction
 5946           log whenever possible.  To disable outgoing
 5947           incremental zone
 5948           transfers, use <command>provide-ixfr</command> <userinput>no</userinput>.
 5949         </para>
 5950           </listitem>
 5951         </varlistentry>
 5952 
 5953         <varlistentry>
 5954           <term><command>message-compression</command></term> <listitem>
 5955         <para>
 5956           If <userinput>yes</userinput>, DNS name compression is
 5957           used in responses to regular queries (not including
 5958           AXFR or IXFR, which always use compression).  Setting
 5959           this option to <userinput>no</userinput> reduces CPU
 5960           usage on servers and may improve throughput.  However,
 5961           it increases response size, which may cause more queries
 5962           to be processed using TCP; a server with compression
 5963           disabled is out of compliance with RFC 1123 Section
 5964           6.1.3.2. The default is <userinput>yes</userinput>.
 5965         </para>
 5966           </listitem>
 5967         </varlistentry>
 5968 
 5969         <varlistentry>
 5970           <term><command>minimal-responses</command></term>
 5971           <listitem>
 5972         <para>
 5973           If set to <userinput>yes</userinput>, then when generating
 5974           responses the server only adds records to the authority
 5975           and additional data sections when they are required (e.g.
 5976           delegations, negative responses).  This may improve the
 5977           performance of the server.
 5978         </para>
 5979         <para>
 5980           When set to <userinput>no-auth</userinput>, the
 5981           server omits records from the authority section
 5982           unless they are required, but it may still add
 5983           records to the additional section.  When set to
 5984           <userinput>no-auth-recursive</userinput>, this
 5985           is only done if the query is recursive.  These
 5986           settings are useful when answering stub clients,
 5987           which usually ignore the authority section.
 5988           <userinput>no-auth-recursive</userinput> is
 5989           designed for mixed-mode servers that handle
 5990           both authoritative and recursive queries.
 5991         </para>
 5992         <para>
 5993           The default is <userinput>no</userinput>.
 5994         </para>
 5995           </listitem>
 5996         </varlistentry>
 5997 
 5998         <varlistentry>
 5999           <term><command>minimal-any</command></term>
 6000           <listitem>
 6001         <para>
 6002           If set to <userinput>yes</userinput>, the server replies with only one
 6003           of the RRsets for the query name, and its covering
 6004           RRSIGs if any, when
 6005           generating a positive response to a query of type
 6006           ANY over UDP, instead of replying with all known
 6007           RRsets for the name.  Similarly, a query for type
 6008           RRSIG is answered with the RRSIG records covering
 6009           only one type. This can reduce the impact of some kinds
 6010           of attack traffic, without harming legitimate
 6011           clients.  (Note, however, that the RRset returned is the
 6012           first one found in the database; it is not necessarily
 6013           the smallest available RRset.)
 6014           Additionally, <option>minimal-responses</option> is
 6015           turned on for these queries, so no unnecessary records
 6016           are added to the authority or additional sections.
 6017           The default is <userinput>no</userinput>.
 6018         </para>
 6019         </listitem>
 6020       </varlistentry>
 6021 
 6022         <varlistentry>
 6023           <term><command>multiple-cnames</command></term>
 6024           <listitem>
 6025         <para>
 6026           This option was used in <acronym>BIND</acronym> 8 to allow
 6027           a domain name to have multiple CNAME records, in violation of
 6028           the DNS standards.  <acronym>BIND</acronym> 9.2 onwards
 6029           always strictly enforces the CNAME rules both in primary
 6030           files and dynamic updates.
 6031         </para>
 6032           </listitem>
 6033         </varlistentry>
 6034 
 6035         <varlistentry>
 6036           <term><command>notify</command></term>
 6037           <listitem>
 6038         <para>
 6039           If <userinput>yes</userinput> (the default),
 6040           DNS NOTIFY messages are sent when a zone the server is
 6041           authoritative for
 6042           changes; see <xref linkend="notify"/>.  The messages are
 6043           sent to the
 6044           servers listed in the zone's NS records (except the primary
 6045           server identified
 6046           in the SOA MNAME field), and to any servers listed in the
 6047           <command>also-notify</command> option.
 6048         </para>
 6049         <para>
 6050           If <userinput>master-only</userinput>, notifies are only
 6051           sent
 6052           for primary zones.
 6053           If <userinput>explicit</userinput>, notifies are sent only
 6054           to
 6055           servers explicitly listed using <command>also-notify</command>.
 6056           If <userinput>no</userinput>, no notifies are sent.
 6057         </para>
 6058         <para>
 6059           The <command>notify</command> option may also be
 6060           specified in the <command>zone</command>
 6061           statement,
 6062           in which case it overrides the <command>options notify</command> statement.
 6063           It would only be necessary to turn off this option if it
 6064           caused secondary zones
 6065           to crash.
 6066         </para>
 6067           </listitem>
 6068         </varlistentry>
 6069 
 6070         <varlistentry>
 6071           <term><command>notify-to-soa</command></term>
 6072           <listitem>
 6073         <para>
 6074           If <userinput>yes</userinput>, do not check the name servers
 6075           in the NS RRset against the SOA MNAME.  Normally a NOTIFY
 6076           message is not sent to the SOA MNAME (SOA ORIGIN), as it is
 6077           supposed to contain the name of the ultimate primary server.
 6078           Sometimes, however, a secondary server is listed as the SOA MNAME in
 6079           hidden primary configurations; in that case,
 6080           the ultimate primary should be set to still send NOTIFY messages to
 6081           all the name servers listed in the NS RRset.
 6082         </para>
 6083           </listitem>
 6084         </varlistentry>
 6085 
 6086         <varlistentry>
 6087           <term><command>recursion</command></term>
 6088           <listitem>
 6089         <para>
 6090           If <userinput>yes</userinput>, and a
 6091           DNS query requests recursion, then the server attempts
 6092           to do
 6093           all the work required to answer the query. If recursion is
 6094           off
 6095           and the server does not already know the answer, it
 6096           returns a
 6097           referral response. The default is
 6098           <userinput>yes</userinput>.
 6099           Note that setting <command>recursion no</command> does not prevent
 6100           clients from getting data from the server's cache; it only
 6101           prevents new data from being cached as an effect of client
 6102           queries.
 6103           Caching may still occur as an effect the server's internal
 6104           operation, such as NOTIFY address lookups.
 6105         </para>
 6106           </listitem>
 6107         </varlistentry>
 6108 
 6109         <varlistentry>
 6110           <term><command>request-nsid</command></term>
 6111           <listitem>
 6112         <para>
 6113           If <userinput>yes</userinput>, then an empty EDNS(0)
 6114           NSID (Name Server Identifier) option is sent with all
 6115           queries to authoritative name servers during iterative
 6116           resolution. If the authoritative server returns an NSID
 6117           option in its response, then its contents are logged in
 6118           the <command>resolver</command> category at level
 6119           <command>info</command>.
 6120           The default is <userinput>no</userinput>.
 6121         </para>
 6122           </listitem>
 6123         </varlistentry>
 6124 
 6125         <varlistentry>
 6126           <term><command>request-sit</command></term>
 6127           <listitem>
 6128         <para>
 6129           This experimental option is obsolete.
 6130         </para>
 6131           </listitem>
 6132         </varlistentry>
 6133 
 6134         <varlistentry>
 6135           <term><command>require-server-cookie</command></term>
 6136           <listitem>
 6137         <para>
 6138           If <userinput>yes</userinput>, require a valid server cookie before sending a full
 6139           response to a UDP request from a cookie-aware client.
 6140           BADCOOKIE is sent if there is a bad or nonexistent
 6141           server cookie.
 6142           The default is <userinput>no</userinput>.
 6143         </para>
 6144         <para>
 6145           Users wishing to test that DNS COOKIE clients correctly handle BADCOOKIE, or who are
 6146           getting a lot of forged DNS requests with DNS COOKIES
 6147           present, should set this to <userinput>yes</userinput>.
 6148           Setting this to <userinput>yes</userinput>
 6149           results in a reduced amplification effect in a reflection
 6150           attack, as the BADCOOKIE response is smaller than
 6151           a full response, while also requiring a legitimate client
 6152           to follow up with a second query with the new, valid, cookie.
 6153         </para>
 6154           </listitem>
 6155         </varlistentry>
 6156 
 6157         <varlistentry>
 6158           <term><command>answer-cookie</command></term>
 6159           <listitem>
 6160         <para>
 6161           When set to the default value of <userinput>yes</userinput>,
 6162           COOKIE EDNS options are sent when applicable in
 6163           replies to client queries. If set to
 6164           <userinput>no</userinput>, COOKIE EDNS options are not
 6165           sent in replies.  This can only be set at the global
 6166           options level, not per-view.
 6167         </para>
 6168         <para>
 6169           <command>answer-cookie no</command> is only intended as a
 6170           temporary measure, for use when <command>named</command>
 6171           shares an IP address with other servers that do not yet
 6172           support DNS COOKIE.  A mismatch between servers on the
 6173           same address is not expected to cause operational
 6174           problems, but the option to disable COOKIE responses so
 6175           that all servers have the same behavior is provided out
 6176           of an abundance of caution. DNS COOKIE is an important
 6177           security mechanism, and should not be disabled unless
 6178           absolutely necessary.
 6179         </para>
 6180           </listitem>
 6181         </varlistentry>
 6182 
 6183         <varlistentry>
 6184           <term><command>send-cookie</command></term>
 6185           <listitem>
 6186         <para>
 6187           If <userinput>yes</userinput>, then a COOKIE EDNS
 6188           option is sent along with the query.  If the
 6189           resolver has previously communicated with the server, the
 6190           COOKIE returned in the previous transaction is sent.
 6191           This is used by the server to determine whether
 6192           the resolver has talked to it before. A resolver
 6193           sending the correct COOKIE is assumed not to be an
 6194           off-path attacker sending a spoofed-source query;
 6195           the query is therefore unlikely to be part of a
 6196           reflection/amplification attack, so resolvers
 6197           sending a correct COOKIE option are not subject to
 6198           response rate limiting (RRL).  Resolvers which
 6199           do not send a correct COOKIE option may be limited
 6200           to receiving smaller responses via the
 6201           <command>nocookie-udp-size</command> option.
 6202           The default is <userinput>yes</userinput>.
 6203         </para>
 6204           </listitem>
 6205         </varlistentry>
 6206 
 6207         <varlistentry>
 6208           <term><command>nocookie-udp-size</command></term>
 6209           <listitem>
 6210         <para>
 6211           This sets the maximum size of UDP responses that are
 6212           sent to queries without a valid server COOKIE. A value
 6213           below 128 is silently raised to 128. The default
 6214           value is 4096, but the <command>max-udp-size</command>
 6215           option may further limit the response size.
 6216         </para>
 6217           </listitem>
 6218         </varlistentry>
 6219 
 6220         <varlistentry>
 6221           <term><command>sit-secret</command></term>
 6222           <listitem>
 6223         <para>
 6224           This experimental option is obsolete.
 6225         </para>
 6226           </listitem>
 6227         </varlistentry>
 6228 
 6229         <varlistentry>
 6230           <term><command>cookie-algorithm</command></term>
 6231           <listitem>
 6232         <para>
 6233           This sets the algorithm to be used when generating the
 6234           server cookie; the options are "aes", "sha1", or "sha256".
 6235           The default is "aes" if supported by the cryptographic
 6236           library; otherwise, "sha256".
 6237         </para>
 6238           </listitem>
 6239         </varlistentry>
 6240 
 6241         <varlistentry>
 6242           <term><command>cookie-secret</command></term>
 6243           <listitem>
 6244         <para>
 6245           If set, this is a shared secret used for generating
 6246           and verifying EDNS COOKIE options
 6247           within an anycast cluster.  If not set, the system
 6248           generates a random secret at startup.  The
 6249           shared secret is encoded as a hex string and needs
 6250           to be 128 bits for AES128, 160 bits for SHA1, and
 6251           256 bits for SHA256.
 6252         </para>
 6253         <para>
 6254           If there are multiple secrets specified, the first
 6255           one listed in <filename>named.conf</filename> is
 6256           used to generate new server cookies.  The others
 6257           are only used to verify returned cookies.
 6258         </para>
 6259           </listitem>
 6260         </varlistentry>
 6261 
 6262         <varlistentry>
 6263           <term><command>rfc2308-type1</command></term>
 6264           <listitem>
 6265         <para>
 6266           Setting this to <userinput>yes</userinput>
 6267           causes the server to send NS records along with the SOA
 6268           record for negative
 6269           answers. The default is <userinput>no</userinput>.
 6270         </para>
 6271         <note>
 6272           <simpara>
 6273             This is not yet implemented in <acronym>BIND</acronym>
 6274             9.
 6275           </simpara>
 6276         </note>
 6277           </listitem>
 6278         </varlistentry>
 6279 
 6280         <varlistentry>
 6281           <term><command>trust-anchor-telemetry</command></term>
 6282           <listitem>
 6283         <para>
 6284           This causes <command>named</command> to send specially formed
 6285           queries once per day to domains for which trust anchors
 6286           have been configured via <command>trusted-keys</command>,
 6287           <command>managed-keys</command>, or
 6288           <command>dnssec-validation auto</command>.
 6289         </para>
 6290         <para>
 6291           The query name used for these queries has the
 6292           form "_ta-xxxx(-xxxx)(...)".&lt;domain&gt;, where
 6293           each "xxxx" is a group of four hexadecimal digits
 6294           representing the key ID of a trusted DNSSEC key.
 6295           The key IDs for each domain are sorted smallest
 6296           to largest prior to encoding. The query type is NULL.
 6297         </para>
 6298         <para>
 6299           By monitoring these queries, zone operators are
 6300           able to see which resolvers have been updated to
 6301           trust a new key; this may help them decide when it
 6302           is safe to remove an old one.
 6303         </para>
 6304         <para>
 6305           The default is <userinput>yes</userinput>.
 6306         </para>
 6307           </listitem>
 6308         </varlistentry>
 6309 
 6310         <varlistentry>
 6311           <term><command>use-id-pool</command></term>
 6312           <listitem>
 6313         <para>
 6314           <emphasis>This option is obsolete</emphasis>.
 6315           <acronym>BIND</acronym> 9 always allocates query
 6316           IDs from a pool.
 6317         </para>
 6318           </listitem>
 6319         </varlistentry>
 6320 
 6321         <varlistentry>
 6322           <term><command>use-ixfr</command></term>
 6323           <listitem>
 6324         <para>
 6325           <emphasis>This option is obsolete</emphasis>.
 6326           To disable IXFR to a particular server or
 6327           servers, see
 6328           the information on the <command>provide-ixfr</command> option
 6329           in <xref linkend="server_statement_definition_and_usage"/>.
 6330           See also
 6331           <xref linkend="incremental_zone_transfers"/>.
 6332         </para>
 6333           </listitem>
 6334         </varlistentry>
 6335 
 6336         <varlistentry>
 6337           <term><command>provide-ixfr</command></term>
 6338           <listitem>
 6339         <para>
 6340           See the description of
 6341           <command>provide-ixfr</command> in
 6342           <xref linkend="server_statement_definition_and_usage"/>.
 6343         </para>
 6344           </listitem>
 6345         </varlistentry>
 6346 
 6347         <varlistentry>
 6348           <term><command>request-ixfr</command></term>
 6349           <listitem>
 6350         <para>
 6351           See the description of
 6352           <command>request-ixfr</command> in
 6353           <xref linkend="server_statement_definition_and_usage"/>.
 6354         </para>
 6355           </listitem>
 6356         </varlistentry>
 6357 
 6358         <varlistentry>
 6359           <term><command>request-expire</command></term>
 6360           <listitem>
 6361         <para>
 6362           See the description of
 6363           <command>request-expire</command> in
 6364           <xref linkend="server_statement_definition_and_usage"/>.
 6365         </para>
 6366           </listitem>
 6367         </varlistentry>
 6368 
 6369         <varlistentry>
 6370           <term><command>treat-cr-as-space</command></term>
 6371           <listitem>
 6372         <para>
 6373           This option was used in <acronym>BIND</acronym>
 6374           8 to make
 6375           the server treat carriage return ("<command>\r</command>") characters the same way
 6376           as a space or tab character,
 6377           to facilitate loading of zone files on a Unix system that
 6378           were generated
 6379           on an NT or DOS machine. In <acronym>BIND</acronym> 9, both UNIX "<command>\n</command>"
 6380           and NT/DOS "<command>\r\n</command>" newlines
 6381           are always accepted,
 6382           and the option is ignored.
 6383         </para>
 6384           </listitem>
 6385         </varlistentry>
 6386 
 6387         <varlistentry>
 6388           <term><command>additional-from-auth</command></term>
 6389           <term><command>additional-from-cache</command></term>
 6390           <listitem>
 6391 
 6392         <para>
 6393           These options control the behavior of an authoritative
 6394           server when
 6395           answering queries which have additional data, or when
 6396           following CNAME
 6397           and DNAME chains.
 6398         </para>
 6399 
 6400         <para>
 6401           When both of these options are set to <userinput>yes</userinput>
 6402           (the default) and a
 6403           query is being answered from authoritative data (a zone
 6404           configured into the server), the additional data section of
 6405           the
 6406           reply is filled in using data from other authoritative
 6407           zones
 6408           and from the cache.  In some situations this is undesirable,
 6409           such
 6410           as when there is concern over the correctness of the cache,
 6411           or
 6412           in servers where secondary zones may be added and modified by
 6413           untrusted third parties.  Also, avoiding
 6414           the search for this additional data speeds up server
 6415           operations
 6416           at the possible expense of additional queries to resolve
 6417           what would
 6418           otherwise be provided in the additional section.
 6419         </para>
 6420 
 6421         <para>
 6422           For example, if a query asks for an MX record for host <literal>foo.example.com</literal>,
 6423           and the record found is "<literal>MX 10 mail.example.net</literal>", normally the address
 6424           records (A and AAAA) for <literal>mail.example.net</literal> are provided as well,
 6425           if known, even though they are not in the example.com zone.
 6426           Setting these options to <command>no</command>
 6427           disables this behavior and makes
 6428           the server only search for additional data in the zone it
 6429           answers from.
 6430         </para>
 6431 
 6432         <para>
 6433           These options are intended for use in authoritative-only
 6434           servers, or in authoritative-only views.  Attempts to set
 6435           them to <command>no</command> without also
 6436           specifying
 6437           <command>recursion no</command> will cause the
 6438           server to
 6439           ignore the options and log a warning message.
 6440         </para>
 6441 
 6442         <para>
 6443           Specifying <command>additional-from-cache no</command> actually
 6444           disables the use of the cache not only for additional data
 6445           lookups
 6446           but also when looking up the answer.  This is usually the
 6447           desired
 6448           behavior in an authoritative-only server where the
 6449           correctness of
 6450           the cached data is an issue.
 6451         </para>
 6452 
 6453         <para>
 6454           When a name server is non-recursively queried for a name
 6455           that is not
 6456           below the apex of any served zone, it normally answers with
 6457           an
 6458           "upwards referral" to the root servers or the servers of
 6459           some other
 6460           known parent of the query name.  Since the data in an
 6461           upwards referral
 6462           comes from the cache, the server is not able to provide
 6463           upwards
 6464           referrals when <command>additional-from-cache no</command>
 6465           has been specified.  Instead, it responds to such
 6466           queries
 6467           with REFUSED.  This should not cause any problems since
 6468           upwards referrals are not required for the resolution
 6469           process.
 6470         </para>
 6471 
 6472           </listitem>
 6473         </varlistentry>
 6474 
 6475         <varlistentry>
 6476           <term><command>match-mapped-addresses</command></term>
 6477           <listitem>
 6478         <para>
 6479           If <userinput>yes</userinput>, then an
 6480           IPv4-mapped IPv6 address matches any address-match
 6481           list entries that match the corresponding IPv4 address.
 6482         </para>
 6483         <para>
 6484           This option was introduced to work around a kernel quirk
 6485           in some operating systems that causes IPv4 TCP
 6486           connections, such as zone transfers, to be accepted on an
 6487           IPv6 socket using mapped addresses.  This caused address-match
 6488           lists designed for IPv4 to fail to match.  However,
 6489           <command>named</command> now solves this problem
 6490           internally.  The use of this option is discouraged.
 6491         </para>
 6492           </listitem>
 6493         </varlistentry>
 6494 
 6495         <varlistentry>
 6496           <term><command>filter-aaaa-on-v4</command></term>
 6497           <listitem>
 6498         <para>
 6499           This option is only available when
 6500           <acronym>BIND</acronym> 9 is compiled with the
 6501           <userinput>--enable-filter-aaaa</userinput> option on the
 6502           "configure" command line.  It is intended to help the
 6503           transition from IPv4 to IPv6 by not giving IPv6 addresses
 6504           to DNS clients unless they have connections to the IPv6
 6505           Internet.  This is not recommended unless absolutely
 6506           necessary.  The default is <userinput>no</userinput>.
 6507           The <command>filter-aaaa-on-v4</command> option
 6508           may also be specified in <command>view</command> statements
 6509           to override the global <command>filter-aaaa-on-v4</command>
 6510           option.
 6511         </para>
 6512         <para>
 6513           If <userinput>yes</userinput>,
 6514           the DNS client is at an IPv4 address, in <command>filter-aaaa</command>,
 6515           and if the response does not include DNSSEC signatures,
 6516           then all AAAA records are deleted from the response.
 6517           This filtering applies to all responses and not only
 6518           authoritative responses.
 6519         </para>
 6520         <para>
 6521           If <userinput>break-dnssec</userinput>,
 6522           then AAAA records are deleted even when DNSSEC is enabled.
 6523           As suggested by the name, this causes the response to not verify,
 6524           because the DNSSEC protocol is designed to detect deletions.
 6525         </para>
 6526         <para>
 6527           This mechanism can erroneously cause other servers to
 6528           not give AAAA records to their clients.
 6529           A recursing server with both IPv6 and IPv4 network connections,
 6530           that queries an authoritative server using this mechanism
 6531           via IPv4, is denied AAAA records even if its client is
 6532           using IPv6.
 6533         </para>
 6534         <para>
 6535           This mechanism is applied to authoritative as well as
 6536           non-authoritative records.
 6537           A client using IPv4 that is not allowed recursion can
 6538           erroneously be given AAAA records because the server is not
 6539           allowed to check for A records.
 6540         </para>
 6541         <para>
 6542           Some AAAA records are given to IPv4 clients in glue records.
 6543           IPv4 clients that are servers can then erroneously
 6544           answer requests for AAAA records received via IPv4.
 6545         </para>
 6546           </listitem>
 6547         </varlistentry>
 6548 
 6549         <varlistentry>
 6550           <term><command>filter-aaaa-on-v6</command></term>
 6551           <listitem>
 6552         <para>
 6553           This is identical to <command>filter-aaaa-on-v4</command>,
 6554           except it filters AAAA responses to queries from IPv6
 6555           clients instead of IPv4 clients.  To filter all
 6556           responses, set both options to <userinput>yes</userinput>.
 6557         </para>
 6558           </listitem>
 6559         </varlistentry>
 6560 
 6561         <varlistentry>
 6562           <term><command>ixfr-from-differences</command></term>
 6563           <listitem>
 6564         <para>
 6565           When <userinput>yes</userinput> and the server loads a new
 6566           version of a primary zone from its zone file or receives a
 6567           new version of a secondary file via zone transfer, it
 6568           compares the new version to the previous one and calculates
 6569           a set of differences.  The differences are then logged in
 6570           the zone's journal file so that the changes can be
 6571           transmitted to downstream secondaries as an incremental zone
 6572           transfer.
 6573         </para>
 6574         <para>
 6575           By allowing incremental zone transfers to be used for
 6576           non-dynamic zones, this option saves bandwidth at the
 6577           expense of increased CPU and memory consumption at the
 6578           primary server.
 6579           In particular, if the new version of a zone is completely
 6580           different from the previous one, the set of differences
 6581           is of a size comparable to the combined size of the
 6582           old and new zone versions, and the server needs to
 6583           temporarily allocate memory to hold this complete
 6584           difference set.
 6585         </para>
 6586         <para><command>ixfr-from-differences</command>
 6587           also accepts <command>master</command> and
 6588           <command>slave</command> at the view and options
 6589           levels, which causes
 6590           <command>ixfr-from-differences</command> to be enabled for
 6591           all primary or secondary zones, respectively.
 6592           It is off by default.
 6593         </para>
 6594         <para>
 6595           Note: if inline signing is enabled for a zone, the
 6596           user-provided <command>ixfr-from-differences</command>
 6597           setting is ignored for that zone.
 6598         </para>
 6599           </listitem>
 6600         </varlistentry>
 6601 
 6602         <varlistentry>
 6603           <term><command>multi-master</command></term>
 6604           <listitem>
 6605         <para>
 6606           This should be set when there are multiple primary servers for a zone
 6607           and the
 6608           addresses refer to different machines.  If <userinput>yes</userinput>, <command>named</command> does
 6609           not log
 6610           when the serial number on the primary is less than what <command>named</command>
 6611           currently
 6612           has.  The default is <userinput>no</userinput>.
 6613         </para>
 6614           </listitem>
 6615         </varlistentry>
 6616 
 6617         <varlistentry>
 6618           <term><command>auto-dnssec</command></term>
 6619           <listitem>
 6620         <para>
 6621           Zones configured for dynamic DNS may use this
 6622           option to allow varying levels of automatic DNSSEC key
 6623           management. There are three possible settings:
 6624         </para>
 6625         <para>
 6626           <command>auto-dnssec allow;</command> permits
 6627           keys to be updated and the zone fully re-signed
 6628           whenever the user issues the command <command>rndc sign
 6629           <replaceable>zonename</replaceable></command>.
 6630         </para>
 6631         <para>
 6632           <command>auto-dnssec maintain;</command> includes the
 6633           above, but also automatically adjusts the zone's DNSSEC
 6634           keys on a schedule, according to the keys' timing metadata
 6635           (see <xref linkend="man.dnssec-keygen"/> and
 6636           <xref linkend="man.dnssec-settime"/>).  The command
 6637           <command>rndc sign
 6638           <replaceable>zonename</replaceable></command> causes
 6639           <command>named</command> to load keys from the key
 6640           repository and sign the zone with all keys that are
 6641           active.
 6642           <command>rndc loadkeys
 6643           <replaceable>zonename</replaceable></command> causes
 6644           <command>named</command> to load keys from the key
 6645           repository and schedule key maintenance events to occur
 6646           in the future, but it does not sign the full zone
 6647           immediately.  Note: once keys have been loaded for a
 6648           zone the first time, the repository is searched
 6649           for changes periodically, regardless of whether
 6650           <command>rndc loadkeys</command> is used.  The recheck
 6651           interval is defined by
 6652           <command>dnssec-loadkeys-interval</command>.)
 6653         </para>
 6654         <para>
 6655           The default setting is <command>auto-dnssec off</command>.
 6656         </para>
 6657           </listitem>
 6658         </varlistentry>
 6659 
 6660         <varlistentry>
 6661           <term><command>dnssec-enable</command></term>
 6662           <listitem>
 6663         <para>
 6664           This indicates whether DNSSEC-related resource
 6665           records are to be returned by <command>named</command>.
 6666           If set to <userinput>no</userinput>,
 6667           <command>named</command> does not return DNSSEC-related
 6668           resource records unless specifically queried for.
 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           This option enables DNSSEC validation in <command>named</command>.
 6679           Note that <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.
 6683         </para>
 6684             <para>
 6685           If set to <userinput>auto</userinput>, DNSSEC validation
 6686           is enabled and a default trust anchor for the DNS root
 6687           zone is used.  If set to <userinput>yes</userinput>,
 6688           DNSSEC validation is enabled, but a trust anchor must be
 6689           manually configured using a <command>trusted-keys</command>
 6690           or <command>managed-keys</command> statement.  The default
 6691           is <userinput>yes</userinput>.
 6692         </para>
 6693         <para>
 6694           The default root trust anchor is stored in the file
 6695           <filename>bind.keys</filename>.
 6696           <command>named</command> loads that key at
 6697           startup if <command>dnssec-validation</command> is
 6698           set to <constant>auto</constant>.  A copy of the file is
 6699           installed along with BIND 9, and is current as of the
 6700           release date.  If the root key expires, a new copy of
 6701           <filename>bind.keys</filename> can be downloaded
 6702           from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.isc.org/bind-keys">https://www.isc.org/bind-keys</link>.
 6703         </para>
 6704         <para>
 6705           (To prevent problems if <filename>bind.keys</filename> is
 6706           not found, the current trust anchor is also compiled in
 6707           to <command>named</command>.  Relying on this is not
 6708           recommended, however, as it requires <command>named</command>
 6709           to be recompiled with a new key when the root key expires.)
 6710         </para>
 6711         <note>
 6712           <para>
 6713             <command>named</command> loads <emphasis>only</emphasis>
 6714             the root key from <filename>bind.keys</filename>.
 6715             The file cannot be used to store keys for other zones.
 6716             The root key in <filename>bind.keys</filename> is ignored
 6717             if <command>dnssec-validation auto</command> is not in
 6718             use.
 6719           </para>
 6720           <para>
 6721             Whenever the resolver sends out queries to an
 6722             EDNS-compliant server, it always sets the DO bit
 6723             indicating it can support DNSSEC responses, even if
 6724             <command>dnssec-validation</command> is off.
 6725           </para>
 6726         </note>
 6727           </listitem>
 6728         </varlistentry>
 6729 
 6730         <varlistentry>
 6731           <term><command>dnssec-accept-expired</command></term>
 6732           <listitem>
 6733         <para>
 6734           This accepts expired signatures when verifying DNSSEC signatures.
 6735           The default is <userinput>no</userinput>.
 6736           Setting this option to <userinput>yes</userinput>
 6737           leaves <command>named</command> vulnerable to
 6738           replay attacks.
 6739         </para>
 6740           </listitem>
 6741         </varlistentry>
 6742 
 6743         <varlistentry>
 6744           <term><command>querylog</command></term>
 6745           <listitem>
 6746         <para>
 6747           Query logging provides a complete log of all incoming
 6748           queries and all query errors. This provides more insight
 6749           into the server's activity, but with a cost to
 6750           performance which may be significant on heavily loaded
 6751           servers.
 6752         </para>
 6753         <para>
 6754           The <command>querylog</command> option specifies
 6755           whether query logging should be active when
 6756           <command>named</command> first starts.
 6757           If <command>querylog</command> is not specified, then
 6758           query logging is determined by the presence of the
 6759           logging category <command>queries</command>.
 6760           Query logging can also be activated at runtime using the
 6761           command <command>rndc querylog on</command>, or
 6762           deactivated with <command>rndc querylog off</command>.
 6763         </para>
 6764           </listitem>
 6765         </varlistentry>
 6766 
 6767         <varlistentry>
 6768           <term><command>check-names</command></term>
 6769           <listitem>
 6770         <para>
 6771           This option is used to restrict the character set and syntax
 6772           of
 6773           certain domain names in zone files and/or DNS responses
 6774           received
 6775           from the network.  The default varies according to usage
 6776           area.  For primary zones (i.e.,
 6777           <command>type master</command>),
 6778           the default is <command>fail</command>.
 6779           For secondary zones (<command>type slave</command>), the
 6780           default is <command>warn</command>.
 6781           For answers received from the network (<command>response</command>),
 6782           the default is <command>ignore</command>.
 6783         </para>
 6784         <para>
 6785           The rules for legal hostnames and mail domains are derived
 6786           from RFC 952 and RFC 821 as modified by RFC 1123.
 6787         </para>
 6788         <para><command>check-names</command>
 6789           applies to the owner names of A, AAAA, and MX records.
 6790           It also applies to the domain names in the RDATA of NS, SOA,
 6791           MX, and SRV records.
 6792           It further applies to the RDATA of PTR records where the owner
 6793           name indicates that it is a reverse lookup of a hostname
 6794           (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT).
 6795         </para>
 6796           </listitem>
 6797         </varlistentry>
 6798 
 6799         <varlistentry>
 6800           <term><command>check-dup-records</command></term>
 6801           <listitem>
 6802         <para>
 6803           This checks primary zones for records that are treated as different
 6804           by DNSSEC but are semantically equal in plain DNS.  The
 6805           default is to <command>warn</command>.  Other possible
 6806           values are <command>fail</command> and
 6807           <command>ignore</command>.
 6808         </para>
 6809           </listitem>
 6810         </varlistentry>
 6811 
 6812         <varlistentry>
 6813           <term><command>check-mx</command></term>
 6814           <listitem>
 6815         <para>
 6816           This checks whether the MX record appears to refer to a IP address.
 6817           The default is to <command>warn</command>.  Other possible
 6818           values are <command>fail</command> and
 6819           <command>ignore</command>.
 6820         </para>
 6821           </listitem>
 6822         </varlistentry>
 6823 
 6824         <varlistentry>
 6825           <term><command>check-wildcard</command></term>
 6826           <listitem>
 6827         <para>
 6828           This option is used to check for non-terminal wildcards.
 6829           The use of non-terminal wildcards is almost always as a
 6830           result of a failure
 6831           to understand the wildcard matching algorithm (RFC 1034).
 6832           This option
 6833           affects primary zones.  The default (<command>yes</command>) is to check
 6834           for non-terminal wildcards and issue a warning.
 6835         </para>
 6836           </listitem>
 6837         </varlistentry>
 6838 
 6839         <varlistentry>
 6840           <term><command>check-integrity</command></term>
 6841           <listitem>
 6842         <para>
 6843           This performs post-load zone integrity checks on primary
 6844           zones.  It checks that MX and SRV records refer
 6845           to address (A or AAAA) records and that glue
 6846           address records exist for delegated zones.  For
 6847           MX and SRV records, only in-zone hostnames are
 6848           checked (for out-of-zone hostnames, use
 6849           <command>named-checkzone</command>).
 6850           For NS records, only names below top-of-zone are
 6851           checked (for out-of-zone names and glue consistency
 6852           checks, use <command>named-checkzone</command>).
 6853           The default is <command>yes</command>.
 6854         </para>
 6855         <para>
 6856           The use of the SPF record to publish Sender
 6857           Policy Framework is deprecated, as the migration
 6858           from using TXT records to SPF records was abandoned.
 6859           Enabling this option also checks that a TXT Sender
 6860           Policy Framework record exists (starts with "v=spf1")
 6861           if there is an SPF record. Warnings are emitted if the
 6862           TXT record does not exist; they can be suppressed with